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30 年 前 (截至 2014 年 ) ， 我 第 一 次 在 学 校 的 第 一 台 Apple II 电脑 中 插入 5.25 英寸 DOS 3.3 磁盘 ， 开 始 研究 
BASIC。 
































那 几 年 我 使 用 多 门 语言 编写 了 很 多 代码 ， 多 到 让 人 难以 置信 。 现 在 我 每 周 还 会 写 代 码 ， 但 是 所 用 的 语言 和 写 
出 的 代码 行 数 都 减少 了 。 
这 些 年 ， 我 见 过 糟糕 的 代码 ， 也 见 过 优秀 的 代码 。 就 我 自己 而 言 ， 写 出 的 代码 也 是 优 劣 各 半 。 奇 怪 的 是 ， 在 
我 的 职业 生涯 中 ， 我 还 没 真正 做 过 程序 员 。 我 自己 运营 一 家 IT 公司 五 年 了 ， 为 大 大 小 小 的 公司 做 过 事 ， 但 是 
大 都 负责 研发 、 技 术 和 运 维 ， 从 未 专门 做 过 程序 员 。 

我 一 直 被 人 使 唤 ， 去 完成 各 项 工作 。 


说 得 简单 一 点 ， 生 意 不 就 是 完成 各 项 工作 吗 ! 经 年 累 月 ， 人 们 已 经 疲惫 ， 不 再 争论 弯 引 号 和 哪 门 语 言 最 适合 
开发 应 用 。 
每 学 一 门 语言 ， 我 都 会 阅读 大 量 相关 的 书籍 ， 因 此 我 知道 你 阅读 导言 是 想 找 什 么 ， 那 我 们 就 直接 进入 正题 
吧 。 











































































































为 什么 要 关注 Django? 























虽然 Django 不 是 完成 工作 唯一 的 Web 框架 ,但 是 我 可 以 确信 一 点 ， 如 果 你 想 编写 简洁 明了 的 代码 ， 想 快速 
构建 高 性 能 、 外 观 精 美的 现代 网 站 ， 那 么 你 一 定 能 从 本 书 中 受益 。 


我 故意 不 与 其 他 语言 和 框架 作 比 较 ， 因 为 那 无 关 紧 机， 所 有 语言 以 及 使 用 它们 构建 的 框架 和 工具 都 有 各 自 的 
优 缺 点 ， 然 而 根据 我 这 些 年 的 经 验 ， 我 完全 认同 Django 是 出 色 的， 能 排 在 前 列 ， 因 为 使 用 它 能 快速 写 出 安全 
牢固 上 且 没 有 缺陷 的 代码 。 


Django 能 出 色 地 完成 某 些 任 务 ， 如 果 需 要 高 级 功能 ， 它 在 表皮 之 下 也 提供 了 支持 。 

此 外 ，Django 是 使 用 Python 构建 的 ， 这 是 一 门 被 认为 是 最 简单 易学 的 编程 语言 。 当 然 ， 这 些 优势 也 带 来 了 
挑战 。Python 和 Django 都 在 表皮 之 下 隐藏 了 众多 强大 的 功能 ， 初 学 者 可 能 难以 理解 。 本 书 就 是 为 此 而 写 
的 。 本 书 旨 在 教 你 如 何 快 速 改进 自己 的 Django 项 目 ， 最 终 学 会 正确 设计 、 开 发 和 部 署 网 站 所 要 掌握 的 全 部 知 


识 。 








































































































































































































最 初 的 The Django Book 是 Adrian 和 Jacob 写 的 ， 他 们 相信 Django 能 让 Web 开发 变 得 更 好 。The Django Book 
出 版 后 ，Django 持续 发 展 、 迅 速 增长 ， 我 想 正 是 应 验 了 这 一 点 。 与 原来 那 本 书 一 样 ， 本 书 也 是 开源 的 ， 欢 迎 
任何 人 做 改进 。 你 可 以 在 本 书 的 网 站 中 提交 评论 和 建议 ， 或 者 给 我 发 电子 邮件 ， 地 址 是 nigel@masteringdjan- 
go.com。 我 与 很 多 人 一 样 ， 在 使 用 Django 的 过 程 中 身心 愉悦 。Django 与 Adrian 和 Jacob 期 望 的 一 样 ， 让 人 
欢心 ， 是 开发 的 好 帮手 。 









































关于 本 书 


这 是 一 本 讲解 Django 的 书 。Django 是 一 个 Web 开发 框架 ， 能 节省 Web 开发 的 时 间 ， 让 整个 过 程 充满 欢乐 。 
使 用 Django 开发 Web 应 用 能 达到 事半功倍 的 效果 。 本 书 对 The Django Book 做 了 全 面 的 修订 和 升级 。The 
Django Book 最 初 由 Apress 于 2007 年 出 版 ， 题 为 The Definitive Guide to Django: Web Development Done 
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Right， 后 来 又 由 两 位 作者 在 2009 年 重新 出 版 ， 
于 GUN 自由 文档 许可 证 (GFDL) 发 布 。 



































而 且 书 名 换 成 了 The Django Book。 后 者 是 一 个 开源 项 目 ， 基 











本 书 可 以 认为 是 The Django Book 的 非 官 方 第 三 版 。 不 过 ， 我 是 否 
是 否认 可 。 对 我 个 人 而 言 ， 我 十 分 希望 The Django Book 能 够 得 到 更 新 ， 因 为 我 就 是 从 那 本 书 入 门 的 。 为 了 
保留 Adrian 和 Jacob 对 The Django Book 的 最 初期 许 ， 本 书 的 源码 在 本 书 的 网 站 上 也 可 以 免费 获取 。 

















本 书 的 主要 目的 是 把 你 打造 成 Django 专家 。 本 书 集中 讲解 两 方面 
































有 这 个 荣幸 ， 还 要 看 Jacob 和 Django 社区 




















的 内 容 。 首 先 ， 深 入 说 明 Django 的 机 制 ， 























教 你 使 用 它 构 建 Web 应 用 。 其 次 ， 适 当 讨 论 高 级 概念 ， 说 明 如 何在 项 目 中 有 效 使 用 相关 的 工具 。 阅 读本 书 你 





将 学 会 快速 开发 强大 网 站 所 需 的 技能 ， 而 且 写 出 的 代码 简 尘 、 易 了 




















本 书 的 第 二 个 目的 〈 没 那么 重要 ) 是 为 程序 员 提供 














本 的 手册 。 目 前 ，Django 已 经 成 熟 ， 很 多 重要 的 商业 网 站 都 使 











维护 。 


份 关 于 Django 长 期 支持 (Long Term Support，LTS) 版 

















它 开发 。 因 此 ， 本 书 意欲 成 为 采用 Django 

















1.8 LTS 的 商业 网 站 的 最 新 权威 参考 资源 。 本 书 电子 版 会 一 直 更 新 ， 直 到 对 Django 1.8 的 支持 结束 (2018 










































































年 ) 。 

如 何 阅读 本 书 

写作 本 书 时 ， 我 尽量 参照 原 书 ， 在 可 读 性 和 作为 参考 好 
长 

习 

某 

定 的 知识 后 ， 再 讨论 更 高 级 的 话题 。 


























F 册 两 方面 做 了 平衡 。 然 而 ，2007 年 之 后 ，Django 有 了 
足 的 发 展 ， 功 能 和 灵活 性 都 提高 了 ， 从 而 引入 了 额外 的 复杂 度 。 在 一 众 Web 应 用 框架 中 ，Django 仍 是 学 

线 最 短 的 ， 但 是 若 想 掌握 Django， 还 是 要 学 习 很 多 知识 。 本 书 保留 了 原 书 的 “通过 实例 学 习 ” 策 略 ， 不 过 
些 较 复杂 的 章节 (如 数据 库 配 置 ) 往 后 移 了 。 因 此 ， 我 们 将 先 使 用 默认 的 配置 学 习 Django 的 机 理 ， 掌 握 一 





























鉴于 此 ， 我 建议 你 按 顺 序 从 第 1 章 读 到 第 13 章 。 这 几 章 是 使 用 Django 的 基础 ， 读 完 之 后 便 能 构建 和 部 署 
Django 驱动 的 网 站 。 具 体 而 言 ， 第 1-6 章 是 “基础 课程 ”， 第 7-12 章 是 较 高 级 的 话题 ， 第 13 章 则 涵盖 部 署 。 





余下 的 几 章 (14-21) 专注 于 特定 的 Django 功能 ， 可 以 按 作 



































F 何 顺序 阅读 。 附 录 是 参考 手册 。 你 可 能 会 经 常 番 





阅 那 些 附 录 和 Django Project 网 站 中 的 免费 文档 ， 回 顾 句法 或 者 快速 概览 Django 某 个 功能 的 作用 。 


所 需 的 编程 知识 











本 书 的 读者 应 该 知道 过 程式 编程 和 面向 对 象 编程 的 基础 知识 :控制 结构 (如 if、while、for) 、 数 据 结构 


























出 


(列表 、 散 列 /字典 ) 、 变 量 、 类 和 对 象 。 如 你 所 想 ， 有 Web 开发 经 验 更 好 ， 但 这 不 是 必须 的 。 本 书 会 尽 











说 明 Web 开发 的 最 佳 实践 。 


所 需 的 Python 知识 





节 

















说 到 底 ，Django 只 是 一 系列 使 用 Python 编程 语言 编写 的 库 。 使 用 Django 开发 网 站 就 是 使 用 这 些 库 编写 











Python 代码 。 因 此 ， 学 习 Django 是 学 习 如 何 使 









































] Python 编程 ， 以 及 理解 Django 库 的 机 理 。 如 果 你 有 使 用 








Python 编程 的 经 验 ， 阅 读本 书 就 没有 障碍 。 总 的 来 说 ，Django 代码 没有 多 少 "魔法 ”( 即 难以 说 明和 理解 的 编 
程 技巧 ) 。 对 你 来 说 ， 学 习 Django 就 是 学 习 Django 的 约定 和 API。 


























即便 没有 Python 编程 经 验 ， 你 也 会 喜欢 上 它 的 。Django 易于 学 习 ， 用 起 来 得 心 应 手 。 本 书 虽 然 不 含 完整 的 
Python 教程 ， 但 是 会 适时 强调 重要 的 Python 特性 和 功能 ， 尤 其 是 无 法 立即 理解 的 代码 。 不 过 ， 我 还 是 建议 你 
阅读 官方 的 Python 教程 。 我 还 建议 你 阅读 Mark Pilgrim 写 的 Dive Into Python， 这 是 一 本 免费 书 ， 可 以 在 线 阅 




















读 ， 地 址 是 http:/www.diveintopython.net/， 这 本 


所 需 的 Django 版 本 





本 书 涵盖 Django 1.8 Long Term Support (LTS) 

















。 这 是 Django 的 长 期 支持 版 本 ， 在 2018 年 4 月 之 前 会 一 直 














也 由 Apress 出 版 过 纸 质 版 。 

















得 到 全 面 支持 。 


如 果 你 用 的 是 早期 的 Django 版本， 建议 你 升级 到 最 新 的 Django 1.8 LTS。 本 书 印刷 时 (2016 年 7 月 ) ， 当 前 
最 新 的 Django 1.8 LTS 生产 版 本 是 1.8.13。 












































如 果 你 使 用 的 是 Django 的 后 续 版 本 ， 要 注意 ， 虽然 Django 的 开发 者 会 尽量 维护 向 后 兼容 性 ， 但 是 偶尔 会 引 
入 不 向 后 兼容 的 改动 。 发 布 记 中 有 每 一 次 发 布 的 改动 ， 地 址 是 https://docs.djangoproject.com/en/dev/releases/。 























寻求 帮助 


Django 的 一 大 优势 是 ， 它 的 用 户 社区 友善 、 乐 于 助人 。 如 果 你 对 Django 的 任何 方面 有 疑问 ， 从 安装 到 应 用 
设计 ， 到 数据 库 设计 和 部 署 ， 都 可 以 在 线 询问 。 


















































。 数 千 名 Django 用 户 经 常 得 django-users 邮件 列表 ， 在 里 面 回答 问题 。 免 费 注册 地 址 http://www.django- 
project.com/r/django-users。 

。 Django 用 户 在 Django IRC 频道 中 实时 聊天 和 互 帮 互 助 。 加 入 Freenode IRC 网 络 中 的 类 jango 频道 
吧 ! 











- xvii 


了 中 


ll 














优秀 的 开源 软件 不 断 涌 现 ， 因 为 总 是 有 那么 一 些 聪明 的 
Django 就 是 一 例 。Adrian 和 Jacob 早已 退出 这 个 项 目 ， 但 是 它们 为 Django 定 的 基调 始终 没 变 。 正 是 这 种 基于 


实战 的 基础 使 得 Django 如 此 成 功 。 鉴 于 他 们 所 做 的 


做 了 编辑 和 重 排 ) 。 


介绍 Django 

















ju 




















昌 一 次 只 能 改 一 个 网 








E Web 早期 阶段 ， 开 发 者 手动 编写 每 个 页 画 




















Django 简介 








开发 者 遇 到 一 些 问 题 无 法 使 用 现 有 的 方案 有 效 解决 。 






































巨大 贡献 ， 我 觉得 最 好 由 他 们 来 介绍 Django (根据 原 书 


Adrian Holovaty 和 Jacob Kaplan-Moss 
2009 年 12 月 





























页 。 随 着 网 站 体 量 的 增 大 ， 这 种 方 





NCSA (National Center for Supercomputing Applications, 
Mosaic 就 是 在 这 里 开发 出 来 的 ) 一 群 富 于 创新 的 黑客 解决 了 这 个 问题 ， 他 们 让 Web 服务 器 派生 外 部 程序 ， 
动态 生成 HIML。 他 们 把 这 一 协议 称 为 通用 网 关 接 口 (Common Gateway Interface，CGI) ， 自 此 ，Web 完全 














变 了 样 。 如 今 ， 很 难 























出 


。 更 新 网 站 要 编辑 HTML， 重 新 设计 要 重新 制作 每 一 个 网 页 ， 而 























式 立马 变 得 繁琐 、 浪 费时 间 ， 最 终 变 得 不 切实 际 。 














国家 超级 计算 应 用 中 心 ， 第 一 款 图 形 Web 浏览 









































想象 CGI 带 来 的 变革 : CGI 不 再 把 HTML 页 面 视 作 硬 盘 中 存储 的 文件 ， 而 是 把 页 面 看 





做 资源 ， 可 以 按 需 动态 生成 。 





CGI 的 开发 促使 了 第 
导致 代码 难以 复 用 ， 














PHP 解决 了 这 些 问 题 

















接 上 能 入 普通 的 HIML 











一 代 动 态 网 站 的 出 现 。 然 而 ，CGI 
而 且 新 手 难 以 编写 和 理解 。 







































































为 程序 员 提 供 多 少 防 
上 述 问 题 以 及 类 似 的 














P 的 多 数 ， 在 Web 开发 界 引起 了 一 阵风 暴 。PHP 现在 是 创建 动态 网 站 最 流行 的 工具 ， 
多 门类 似 的 语言 (ASP、JSP， 等 等 ) 都 参照 了 PHP 的 设计 原则 。PHP 的 主要 创新 是 易于 使 用 : PHP 代码 直 
FP; 对 学 过 HTML 的 人 来 说 ， 学 习 曲 线 极为 平缓 。 


但 是 ，PHP 也 有 自身 的 问题 : 就 是 因为 易于 使 用 ， 写 出 











自身 也 有 问题 : CGI 脚本 包含 大 量 重复 的 样板 代码 ， 


















































的 代码 凑 乱 、 重 复 ， 设 计 不 周 。 更 糟 的 是 ，PHP 没有 

















正安 全 漏洞 的 保护 机 制 ， 很 多 PHP 开发 者 意识 到 这 一 点 再 去 学 习 相 关 的 知识 就 晚 了 。 





缺陷 直接 促使 了 “第 三 代 ”Web 开发 





心 ， 现 在 Web 开发 者 每 天 所 做 的 工作 越 来 越 多 。 
































Django 就 是 为 了 迎接 这 些 雄 心 而 诞生 的 。 


Django 的 历史 

















框架 的 涌现 。Web 开发 的 新 方式 也 提升 了 人 们 的 雄 






































Django 是 从 真实 的 应 用 中 成 长 起 来 的 ， 由 美国 堪萨斯 放 
秋天 ， 那 时 Lawrence Journal-World 报社 的 Web 开发 者 Adrian Holovaty 和 Simon Willison 在 尝试 使 用 Python 




















构建 应 用 。 





























| 劳伦斯 的 一 个 Web 开发 团队 编写 。 它 诞生 于 2003 年 


























World Online 团队 负责 制作 和 维护 本 地 的 几 个 新 闻 网 站 ， 在 新 闻 界 特有 的 快 节奏 开发 环境 中 逐渐 发 展 壮 大 。 
































能 开发 一 个 节省 时 间 






































那些 网 站 (包括 LJWorld.com、Lawrence.com 和 KUsports.com) 的 记者 (和 管理 层 ) 不 断 要 求 增加 功能 ， 而 
量 整 个 应 用 要 在 紧张 的 周期 内 快速 开发 出 来 ， 通 常 只 有 





几 天 或 几 小 时 。 因 此 ，Simon 和 Adrian 别 无 他 法 ， 只 











的 Web 开发 框架 ,这样 他 们 才能 大 

















E 极 短 的 截止 日 期 之 前 构建 出 易于 维护 的 应 用 。 








XiX 


经 过 一 段 时 间 的 玫 

















F 发 后 ， 那 个 框架 已 经 足够 驱动 世界 上 最 大 的 在 线 网 站 了 。2005 年 夏天 ， 团队 ( 彼 时 Jacob 


Kaplan-Moss 已 经 加 入 ) 决定 把 框架 作为 开源 软件 发 布 出 来 。 他 们 在 2005 年 7 月 发 布 了 那个 框架 ， 将 其 命名 


为 Django 


取 自 一 十 











吉他 手 Django Reinhardt。 








这 段 历史 相当 重要 ， 因 为 说 清 了 两 件 要 事 。 首 先是 Django 的 ”发 力 点 "。Dijango 诞生 于 新 闻 界 ， 


了 几 个 特别 适合 “内 容 型 "网 站 使 用 的 功能 〈 如 管理 后 台 ， 参 见 























第 5 章 ) 。 


craigslist.org 和 washingtonpost.com 这 样 动态 的 数据 库 驱 动 型 网 站 使 用 。 


不 过 ， 不 要 
有 效 工 具 。 

















第 二 点 是 ，Django 最 初 的 型 


因此 而 灰心 。 虽 
( 某 些 方面 “特别 ”高 效 与 某 些 方面 不 高 效 是 由 区 别 的 。) 


E 仿 :塑造 了 开源 社区 的 文化 。Django 是 从 真实 代码 中 提取 出 来 的 ， 而 不 是 科 下 


[HI 














或 商业 产品 ， 
天 都 


已 




















专注 于 解决 





负载 下 的 性 能 恨 好 。 


使 用 Django 能 在 极 短 的 时 间 内 构建 全 夯 




















重复 劳作 的 痛苦 
决 问题 提供 了 清 


。 为 此 ， 它 




















然 Django 特别 适合 开发 这 种 网 站 ， 但 是 这 并 没 





























Django 的 开发 者 自身 所 面 对 的 问题 。 因 此 ，Django 


























阻碍 它 成 为 开发 全 





























因此 它 提 供 


这 些 功 能 适合 Amazon.com、 





F 何 动态 网 站 的 











项 目 





直 在 积极 改进 ， 几 乎 每 一 


变化 。Django 框架 的 维护 者 一 心 确保 它 能 节省 开发 者 的 时 间 ， 确 保 开发 出 的 应 用 易于 维护 ， 而 且 在 高 









































为 常用 的 Web 开发 模式 提供 了 高 


i 动态 的 网 站 。Django 的 主旨 是 让 你 集中 精力 在 有 趣 
层 抽 象 ， 为 常见 的 编程 任务 提供 了 捷径 ， 还 为 解 
晰 的 约定 。 与 此 同时 ，Django 尽量 做 到 不 挡 路 ， 允 许 你 在 必要 时 脱离 框架 。 




















的 工作 上 ， 减轻 








我 们 之 所 以 写 这 本 书 ， 是 因为 我 们 坚信 ，Django 能 把 Web 开发 变 得 更 好 。 本 书 旨 在 教 你 如 何 快速 改进 自己 


的 Django 项目 ， 


最 终 学 会 J 





E 确 设计 、 开 发 和 部 署 网 站 所 要 掌握 的 全 部 知识 。 





xx - Django 简介 





第 1 章 新 手 入 门 


开始 使 用 Django 之 前 有 两 件 重要 的 事 要 做 : 





1， 安 装 Django (明摆着 的 ) 
2.， 适当 理解 模型 -视图 -控制 器 (Model-View-Controlletr，MVC) 设计 模式 


首先 要 安装 Django， 这 一 步 特别 简单 ， 本 章 前 半 部 分 会 详细 说 明 。 第 二 点 同样 重要 ， 如 果 你 刚 接触 编程 ， 或 
者 之 前 使 用 的 编程 语言 没有 把 数据 和 显示 数据 的 逻辑 区 分 开 ， 更 要 理解 。Django 的 哲学 建立 在 " 松 耦 合 "之 
上 ， 这 正 是 MVC 背后 的 哲学 。 本 书 会 不 断 深入 说 明 松 耦 合 和 MVC， 如 果 你 对 MVC 知之 甚 少 ， 最 好 别 跳 过 
本 章 后 半 部 分 ， 因 为 理解 MVC 之 后 ， 理 解 Django 就 容易 多 了 。 

































































1.1 安装 Django 


学 习 使 用 Django 之 前 ， 必 须 在 电脑 中 安装 一 些 软件 。 幸 好 ， 这 个 过 程 很 简单 ， 分 为 下 述 三 步 : 
1. 安装 Python 
2.， 安装 Python 虚拟 环境 
3， 安 装 Django 
如 果 你 不 知道 怎么 做 ， 别 担心 ， 本 章 假定 你 以 前 从 未 在 命令 行 中 安装 过 软件 ， 会 一 步 步 说 明 安 装 过 程 。 


本 节 针 对 使 用 Windows 系统 的 读者 。 虽 然 很 多 Django 用 户 使 用 *nix 和 OS X， 但 是 大 多 数 新 手 用 的 是 Win- 
dows。 如 果 你 用 的 是 Mac 或 Linux， 网 上 有 大 量 资源 一 一 首先 应 该 阅读 Django 的 安装 说 明 。 











对 Windows 用 户 来 说 ， 你 的 电脑 应 该 可 以 运行 任何 最 近 的 Windows 版 本 (Vista、7、8.1 或 10) 。 本 章 还 假 
设 你 在 桌面 电脑 或 笔记 本 电脑 中 安装 Pjango， 而 且 使 用 开发 服务 器 和 SQLite 运行 书 中 的 所 有 示例 代码 。 目 
前 ， 对 新 手 来 说 ， 这 是 安装 Django 最 简单 、 最 好 的 方式 。 











如 果 你 想 使 用 更 为 高 级 的 方式 安装 Django， 请 阅读 第 13 章 、 第 20 章 和 第 21 草 。 


如 果 使 用 Windows， 我 建议 你 尝试 使 用 Visual Studio 做 Django 开发。 为 了 给 Python 和 Django 
程序 员 提 供 支 持 ，Microsoft 投入 了 很 多 精力 ， 为 Python/Django 提供 了 全 面 的 IntelliSense 文 
持 ， 而 且 把 Django 的 所 有 命令 行 工具 都 集成 到 VS IDE 中 了 。 


重要 的 一 点 是 ，VS 完全 免费 。 我 知道 没 人 会 想到 MS 会 免费 提供 ， 但 这 是 千 真 万 确 的 ! 


附录 G 详细 说 明了 Visual Studio Community 2015 的 安装 方法 ， 还 为 在 Windows 中 做 Django 开 
发 给 出 了 几 个 小 贴 十 。 














1.2 安装 Python 





Django 完全 使 用 Python 编写 ， 因 此 安装 框架 的 第 一 步 是 安装 Python。 





1.2.1 Python 版 本 


Django 1.8 LTS 支持 Python 2.7、3.3、3.4 和 3.5。 对 各 个 Python 版 本 来 说 ，Django 只 支持 最 新 的 微 版 本 
(A.B.C) 。 


如 果 你 只 想 试用 Django， 使 用 Python 2 还 是 Python 3 没有 关系 。 然 而 ， 如 果 你 准备 开发 一 个 线 上 网 站 ， 应 该 
把 Python 3 作为 第 一 选择 。Python 的 维基 使 用 简洁 的 语言 说 明了 这 人 么 做 的 原因 











简单 来 说 ，Python 2X 已 经 过 时 ，Python 3Xx 是 这 门 语言 的 现在 和 未 来 。 
除非 有 特别 理由 使 用 Python 2 〈 例 如 ， 要 使 用 过 时 的 库 ) ,否则 应 该 使 用 Python 3 。 
注意 


本 书 所 有 代码 示例 都 是 用 Python 3 编写 的 。 


1.2.2 安装 过 程 


如 果 你 用 的 是 Linux 或 Mac OS X， 系 统 可 能 已 经 预 装 了 Python。 在 命令 提示 符 (在 OSX 中 使 用 Applica- 
tions/Utilities/Terminal) 输入 python， 如 果 看 到 类 似 下 面 的 输出 ， 说 明 已 经 安装 了 Python: 


Python 2.7.5 (default, June 27 2015, 13:20:20) 
[GCC x.x.x] on xxx Type "help", "copyright", "credits" 
or "license" for more information. 


可 以 看 出 ， 上 述 示 例 中 的 Python 交互 模式 在 Python 2.7 中 运行 。 没 有 经 验 的 用 户 可 能 受骗 。 在 
Linux 和 Mac OS X 设备 中 ， 经 常会 同时 安装 Python 2 和 Python 3。 如 果 你 的 系统 是 这 样 ， 要 
在 所 有 命令 前 面 输入 python3， 而 不 是 python， 这 样 才 会 使 用 Python 3 运行 Django。 











假如 你 的 系统 中 没有 安装 Python， 那 么 首先 要 下 载 安 装 程序 。 访 问 https://www.python.org/downloads/， 点 击 
文字 为 “Download Python 3.x.x” 的 黄色 大 按钮 。 


写作 本 书 时 ，Python 的 最 新 版 是 3.5.1。 你 阅读 本 书 时 ， 可 能 有 更 新 ， 所 以 版 本 号 可 能 稍 有 不 同 。 


别 下 载 2.7x 版 , 这 是 旧版 Python。 本 书 所 有 代码 都 是 用 Python 3 编写 的 ， 如 果 尝 试 使 用 Python 2 运行 ， 会 
遇 到 兼容 问题 。 


Python 安装 程序 下 载 完毕 后 ， 双 击 下 载 文件 夹 里 的 "python-3 xxmsi"， 运 行 安装 程序 。 安 装 过 程 与 其 他 Win- 
dows 程序 一 样 ， 如 果 你 以 前 安装 过 软件 ， 那 就 没有 问题 ， 不 过 有 一 个 选项 极为 重要 ， 一 定 要 定制 。 
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别 记 了 接 下 来 的 那 一 步 ，Windows 中 的 多 数 问 题 都 是 由 于 没有 正确 设置 pythonpath (对 Python 
较为 重要 的 一 个 变量 ) 。 














默认 情况 ，Python 可 执行 文件 不 会 加 入 Windows 的 PATH 变量 。 知 想 正 
有 Python。 和 幸好， 这 个 问题 易于 解决 : 


< 


使 用 Django，PATH 变量 中 必须 





。 对 Python 34.x 来 说 ， 安 装 程序 打开 定制 窗口 时 ,“Add python.exe to Path” 选 项 没有 选中 ， 一定 要 把 这 
个 选项 改 为 “Will be installed on local hard drive”， 如 图 1-1 所 示 。 


。 对 Python 3.5.x 来 说 ， 安 装 之 前 一 定 要 选中 “Add Python 3.5 to PATH”( 图 1-2) 。 

















Customize Python 3.4.3 


Select the way you want features to be installed. 
Click on the icons in the tree below to change the 
Way features will be installed. 


Register Extensions 
To/ Tk 
Documentation 


XX 7| Et 


= Willbe installed on local hard drive 


Prepend C:\f Ea Entire feature will be installed on local hard drive 
variable. This 
command pr x Entirefeature will be unavailable 

















This feature requires 0KB on your hard drive. 








图 1-1， 把 Python 添加 到 PATH 中 (3.4.x 版 ) 
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Install Python 3.5.1 (32-bit) 


Select Install Now to install Python with default settings, or choose 
Customize to enable or disable features. 


oa Python 3.5 2-bit) Seti 
外 Install Now 
Ci\Users\nige\AppData\Local\Programs\Python\Python35-32 
Includes IDLE, pip and documentation 


Creates shortcuts and file associations 


一 Customize installation 
Choose location and features 


thon 
2 J ft Install launcher for all users (recommended) 


Windows Add Python 3.5 to PATH Cancel 








图 1-2， 把 Python 添加 到 PATH 中 (3.5.x 版 ) 











安装 好 Python 之 后 ， 应 该 重新 打开 命令 窗口 ， 然 后 在 命令 提示 符 中 输入 python， 看 有 没有 输出 类 似 下 面 的 内 


容 : 
Python 3.5.1 (v3.5.1:37a07cee5969，Dec 6 2015, 


01:38:48) [MSC v.1900 32 bit (Intel)] on win32 Type "help", "copyright", "credits" 
or "license" for more information. 


>>> 


既然 已 经 打开 命令 提示 符 ， 那 就 再 做 一 件 重 要 的 事 吧 。 按 CTRL-C 键 ， 退 出 Python。 在 命令 提示 符 中 输入 下 
述 命令 ， 然 后 按 回 车 键 : 











python -m pip install -U pip 





这 个 命令 的 输入 类 似 下 面 这 样 : 











C:\Users\nigel>python -m pip install -U pip 
Collecting pip 
Downloading pip-8.1.2-py2.py3-none-any.whl (1.2MB) 
100% | ################## 间 #### 间 # 间 # 间 ########| 1.2MB 198kB/s 
Installing collected packages: pip 
Found existing installation: pip 7.1.2 
Uninstalling pip-7.1.2: 
Successfully uninstalled pip-7.1.2 
Successfully installed pip-8.1.2 




















现在 ， 你 无 须知 道 这 个 命令 的 具体 作用 。 简 单 来 说 ，pip 是 Python 的 包 管理 工具 ， 用 于 安装 Python 包 。pip 


是 “Pip Installs Packages* 的 递归 缩写 。pip 对 安装 过 程 中 接 下 来 的 一 步 十 分 重要 ， 但 是 首先 我 们 要 确保 运行 的 
是 pip 的 最 新 版 (写作 本 书 时 是 8.1.2 版 ) ， 上 述 命令 就 是 这 个 作 



































Jo 
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1.3 安装 Python 虚拟 环境 


| 


如 果 你 准备 使 用 Microsoft Visual Studio (VS) ， 别 再 往 下 读 了 ， 请 跳 到 附录 G。VS 只 要 求 你 
安装 Python， 剩 下 的 事 都 交 给 VS 的 集成 开发 环境 (Integrated Development Environment， 
IDE) 。 


电脑 中 的 软件 相互 依赖 ， 每 个 程序 都 要 依赖 某 些 其 他 程序 ， 而 且 要 找到 运行 其 他 软件 的 设置 (环境 变量 ) 。 


编写 新 软件 程序 时 ， 可 能 (经常) 要 修改 其 他 软件 所 需 的 依赖 或 环境 变量 。 这 一 步 可 能 会 导致 各 种 问题 ， 因 
此 要 避免 。 


Python 虚拟 环境 能 解决 这 个 问题 。 它 把 软件 所 需 的 全 部 依赖 和 环境 变量 包装 到 一 个 文件 系统 中 ， 与 电脑 中 的 
其 他 软件 隔离 开 。 


看 过 其 他 教程 的 读者 可 能 会 注意 到 ， 别 的 教程 往往 说 这 一 步 是 可 选 的 。 我 不 这 么 认为 ， 很 多 
Django 核心 开发 者 也 不 同意 这 么 做 。 


使 用 虚拟 环境 开发 Python 应 用 程序 (包括 Django) 的 优点 很 明显 ， 在 此 无 需 获 述 。 对 新 手 来 
说 ， 你 只 要 相信 我 就 行 了 : 在 虚拟 环境 中 做 Django 开发 不 是 可 选 的 。 





Python 的 虚拟 环境 工具 是 virtualenv， 可 以 在 命令 行 中 使 用 pip 安装 : 





pip install virtualenv 
命令 窗口 中 的 输出 应 该 像 下 面 这 样 : 


C:\Users\nigel>pip install virtualenv 
Collecting virtuaLenv 
Downloading virtualenv-15.0.2-py2.py3-none-any.whl (1.8MB) 
100% | 大 帮 大 帮 大 夺 振 拓 村 振 持 桂 振 幸 乡 丧 | 1.8MB 323kB/s 
Installing collected packages: virtualenv 
Successfully iinstalled virtualenv-15.0.2 


安装 好 virtualenv 之 后 ， 输 入 下 述 命 令 ， 为 你 的 项 目 创建 一 个 虚拟 环境 : 


virtualenv env_mysite 


EE > 


网 上 的 示例 大 都 使 用 “env” 做 环境 名 称 。 这 样 不 好 ， 主 要 原因 是 ， 可 能 有 多 个 虚拟 环境 测试 不 
同 的 配置 ， 而 “env” 不 便于 区 分 各 个 环境 。 例 如 ， 你 可 能 会 开发 一 个 必须 使 用 Python 2.7 和 
Python 3.4 运行 的 应 用 程序 。 此 时 ， 把 环境 命名 为 “env_someapp_python27” 和 
“env_someapp_python34”， 比 命名 为 “env” 和 “env1” 更 易于 区 分 二 者 。 





这 里 ， 简 单 起 见 ， 我 把 环境 命名 为 "env_mysite"， 因 为 我 们 的 项 目 只 会 使 用 这 么 一 个 虚拟 环境 。 上 述 命令 的 输 
出 应 该 类 似 下 面 这 样 : 
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C:\Users\nigel>virtualenv env_mysite Using base prefix 'c:\\users\\nigel\\appdata\\lo\ 
cal\\programs\\python\\python35-32" 

New python executable in C:\Users\nigel\env mysite\Scripts\python.exe 

Installing setuptools, pip, wheel...done. 


等 virtualenv 设置 好 新 的 虚拟 环境 之 后 ， 打 开 Windows 资源 管理 器 ， 看 一 下 virtualenv 为 我 们 创建 了 什 
么 。 在 家 目录 中 ， 会 看 到 一 个 名 为 \env_mysite 的 文件 夹 (或 者 为 虚拟 环境 起 的 其 他 名 称 ) 。 打 开 那 个 文件 
夹 ， 会 看 到 下 述 结构 : 








\Include 
\Lib 
\Scripts 
\src 








virtualenv 创建 了 一 个 完整 的 Python 安装 ， 它 与 其 他 软件 是 隔离 开 的 ， 因 此 开发 项 目 时 不 会 影响 系统 中 的 其 
他 软件 。 


若 想 使 用 这 个 新 建 的 Python 虚拟 环境 ， 要 将 其 激活 。 回 到 命令 提示 符 ， 输 入 下 述 命令 : 








env_mysite\scripts\activate 
这 个 命令 会 运行 虚拟 环境 中 \scripts 文件 夹 里 的 activate 脚本 。 你 会 发 现 ， 现 在 命令 提示 符 变 了 : 
(env_mysite) C:\Users\nigel> 


命令 提示 符 开头 的 (env_mysite) 是 告诉 你 ， 你 正在 那个 虚拟 环境 中 。 下 一 步 安 装 Django。 





mi 


1.4 安装 Django 


至 此 ， 我 们 安装 了 Python， 也 搭建 了 虚拟 环境 。 接 下 来 安装 Django 就 超级 简单 了 ， 只 需 输 入 下 述 命令 : 
pip install django==1.8.13 


上 述 命令 告诉 pip， 让 它 把 Django 安装 到 虚拟 环境 中 。 命 令 的 输出 应 该 类 似 下 面 这 样 : 





(env_mysite) C:\Users\nigel>pip install django==1.8.13 
Collecting django==1.8.13 
Downloading Django-1.8.13-py2.py3-none-any.whL (6.2MB) 
100% | ## 形 ## 枯 ## 枯 ## 枯 ## 基 ## 枯 ## 基 ##########################| 6.2MB 107kB/s 
Installing collected packages: django 
Successfully installed django-1.8.13 


这 里 ， 我 们 明确 告诉 pip 安装 Django 1.8.13， 即 写作 本 书 时 Django 1.8 LTS 的 最 新 版 。 安 装 Django 时 ， 最 好 
访问 Django Project 网 站 ， 看 看 Django 1.8 LTS 的 最 新 版 是 什么 。 


0 


以 防 你 好 奇 ， 我 告诉 你 ， 输 入 pip install django 会 安装 Django 的 最 新 稳定 版 。 如 果 想 知道 
如 何 安装 Django 的 最 新 开发 版 ， 请 阅读 第 20 章 。 











安装 好 之 后 ， 我 们 应 该 花 点 时 间 做 些 测试 。 在 虚拟 环境 的 命令 提示 符 中 输入 python， 然 后 按 回 车 键 ， 启 动 
Python 交互 式 解释 器 。 如 果 成 功 安装 ， 应 该 能 导入 django 模块 : 





(env_mysite) C:\Users\nigel>python Python 3.5.1 (v3.5.1:37a07cee5969，Dec 6 2015, 
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01:38:48) [MSC v.1900 32 bit (InteL)] on win32 Type "help", "copyright", "credits" 
r "License"” for more information . 

>>> import django 

>>> django.get_version() 

'1.8.13" 


5 安装 数据 库 














完成 本 书 的 示例 不 必 做 这 一 步 。Django 默认 自 带 SQLite。 这 个 数据 库 无 需 配置 。 如 果 你 想 使 用 “大 型 数据库 
引擎， 如 PostgreSQL、MySQL 或 Oracle， 请 阅读 第 21 章 。 














1.6 新 建 项 目 


安装 好 Python、Django 和 数据 库 服务 器 / 库 (可 选 ) 之 后 ， 可 以 开始 开发 Django 应 用 程序 了 。! 第 一 步 是 创 
建 项 目 。 








一 个 项 目 是 一 个 Django 实例 的 一 系列 设置 。 如 果 这 是 你 第 一 次 使 用 Django， 要 做 些 初 始 设置 。 具 体 来 说 ， 
你 要 自动 生成 一 些 代码 ， 创 建 一 个 Django 项 目 ， 即 Django 实例 的 一 系列 设置 ， 包 括 数据 库 配 置 、Django 相 
关 的 选项 和 应 用 程序 相关 的 设置 。 








我 假设 你 现在 仍然 运行 着 前 一 步 那个 虚拟 环境 。 如 果 没 有 ， 请 执行 env_mysite\scripts\activate\ 命令 ， 再 
次 激活 那个 环境 。 在 虚拟 环境 的 命令 行 中 运行 下 述 命令 : 





django-admin startproject mysite 








上 述 命令 会 在 当前 目录 (这 里 是 \env_mysite\) 中 新 建 mysite 目录 。 如 果 你 不 想 在 根 目录 中 创建 项 目 ， 可 以 
新 建 一 个 目录 ， 然 后 进入 其 中 ， 再 运行 startproject 命令 。 





提醒 


不 要 使 用 Python 或 Django 的 组 件 名 命名 项 目 。 具 体 而 言 ， 不 要 使 用 "django”( 与 Django 冲 
突 ) 或 “test” (与 Python 内 置 的 一 个 包 冲 突 ) 这 样 的 名 称 。 


我 们 来 看 一 下 startproject 为 我 们 创建 了 什么 : 


mysite/ 
manage.py 
mysite/ 
__init .py 
settings.py 
urls.py 
wsgi.py 


这 些 文件 是 : 


。 外 层 的 mysite/ 根 目录 是 项 目的 容器 。 这 个 目录 的 名 称 对 Django 没有 什么 作用 ， 你 可 以 根据 喜好 重 命 


























1. 在 中 文 版 中 ,“ 应 用 程序 ”对 应 于 “application”*,“ 应 用 ”对 应 于 “app”。 在 一 般 的 Web 开发 中 ， 这 二 者 几乎 没什么 区 别 ， 但 是 在 
Django 中 二 者 有 一 个 明显 的 区 别 : application 是 指 一 个 完整 的 Web 程序， 而 app 是 指 一 个 可 复 用 的 包 ， 可 以 “插入 ”其 他 Django 
应 用 程序 中 。 望 读者 在 阅读 时 注意 区 分 。 译 者 注 
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名 。 


。 manage.py 是 一 个 命令 行 实用 脚本 ， 可 以 通过 不 同 的 方式 与 Django 项 目 交 互 。 这 个 文件 的 详细 说 明 参 
见 Django Project 网 站 。 


。 内 部 的 mysite/ 目录 是 项 目的 Python 包 。 导 和 人 这 里 面 的 内 容 时 要 使 用 目录 的 名 称 (如 


mysite.urls) 。 


。 mysite/init.py 是 一 个 空 文件 ， 目 的 是 让 Python 把 这 个 目录 识别 为 Python 包 。 (如 果 你 刚 接触 
Python ， 关 于 包 的 说 明 请 阅读 Python 官方 文档 。) 


。 mysite/settings.py 是 Django 项 目的 设置 /配置 。 附 录 D 对 设置 做 了 详细 说 明 。 


。 mysite/urls.py 是 Django 项 目的 URL 声明 ， 即 Django 驱动 的 网 站 的 “目录 ”。 第 2 章 和 第 7 章 将 进 
步 说 明 URL。 


。 mysite/wsgi.py 是 兼容 WSGI 的 Web 服务 器 的 和 人口 点 ， 用 于 伺服 项 目 。 详 情 参见 第 13 章 。 



















































































1.6.1 Django 的 设置 



































接 下 来 ， 编 辑 mysite/settings.py。 这 是 一 个 普通 的 Python 模块 ， 在 模块 层 定义 了 一 些 变量 ， 表 示 Django 
的 设置 。 编 辑 settings.py 的 第 一 步 是 把 TIME_ZONE 设 为 你 所 在 的 时 区 。 注 意 文 件 顶 部 的 INSTALLED_APPS 设 
置 ， 其 值 是 这 个 Django 实例 中 激活 的 全 部 Django 应 用 。 一 个 应 用 可 以 在 多 个 项 目 中 使 用 ， 而 且 应 用 可 以 打 
包 ， 供 其 他 项 目 使 用 。 默 认 情 况 下 ，INSTALLED_APpPSs 包含 下 述 应 用 ， 这 些 都 是 Django 自 带 的 : 
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TT 




































































。 django.contrib.admin: 管理 后 台 


。 django.contrib.auth: 身份 验证 系统 


。 django.contrib.contenttypes: 内 容 类 型 框架 








。 django.contrib.sessions: 会 话 框架 
。 django.contrib.messages: 消息 框架 


。 django.contrib.staticfiles: 管理 静态 文件 的 框架 











nl 


cl 

















Django 项 目 默认 包含 这 些 应 用 ， 这 是 为 常见 场景 所 做 的 约定 。 甚 中 某 些 应 用 要 使 用 数据 库 
要 在 数据 库 中 创建 所 需 的 表 。 为 此 ， 运 行 下 述 命令 : 











因此 使 用 之 前 






































python manage.py migrate 











migrate 命令 查看 INSTALLED_APPS 设置 ， 根 据 settings.py 文件 中 的 数据 库 设 置 ， 以 及 应 用 自 带 的 数据 局 
(后 文 说 明 ) 创建 所 需 的 数据 库 表 。 每 执行 一 个 迁移 都 会 看 到 一 个 消息 。 








迁移 





下 

















1.6.2 开发 服务 器 





下 面 确 认 Django 项 目 是 否 能 运行 。 进 入 外 层 mysite 目录 ( 妇 








J 


果 你 现 处 别 的 位 置 ) ， 然 后 运行 下 述 命令 : 














python manage.py runserver 





在 命令 行 中 将 看 到 下 述 输出 : 





Performing system checks... 


0 errors found June 12, 2016 - 08:48:58 Django version 1.8.13, using settings 'mysite\ 
.Settings' 

Starting deveLopment server at http://127.0.0.1:8000/ 

Quit the server with CTRL-BREAK. 
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我 们 启动 的 是 Django 开发 服务 器 ， 这 是 一 个 轻 量 级 Web 服务 器 ， 完 全 使 用 Python 编写 。Django 自 带 这 个 服 
务 器 ， 以 便 快 速 开 发 ， 而 不 用 花 时 间 配 置 生产 服务 器 (如 Apache) 一 一 这 一 步 在 准备 好 部 署 到 生产 环境 时 再 
做 。 


注意 ， 别 在 任何 生产 环境 中 使 用 这 个 服务 器 ， 它 只 能 在 开发 过 程 中 使 用 。 


现在 ， 开 发 服务 器 正在 运行 ， 在 Web 浏览 器 中 访问 http://127.0.0.1:8000/。 你 会 看 到 一 个 淡 蓝 色 背 景 的 “Wel- 
come to Django” 页 面 (图 1-3) 。 这 证 明 Django 能 正常 运行 ! 





[ Welcome to Django ~、 


€ @ 省 | 127.0.0.1:800( 包间 南 


lt worked! 
Congratulations on your first Django-powered page. 


Of course, you haven't actually done any work yet. Next, start your first app by running python manage.py startapp 
[app_label]. 


You're seeing this message because you have DEBUG = True in your Django settings file and you haven't configured 
any URLs. Get to work! 


图 1-3，Django 的 欢迎 页 面 


自动 重新 加 载 服 务 器 


开发 服务 器 会 根据 需要 在 每 次 请 求 时 自动 重新 加 载 Python 代码 ， 我 们 无 需 自己 动手 重启 服务 
器 ， 改 动 的 代码 自动 生效 。 然 而 ， 有 些 操作 ， 如 添加 文件 ， 不 会 触发 重启 ， 因 此 在 这 些 情况 下 
需要 自己 动手 重启 服务 器 。 

















1.7 模型 -视图 -控制 器 设计 模式 


MVC 这 个 概念 存在 很 长 时 间 了 ， 但 是 随 着 互联 网 的 发 展 才 被 更 多 的 人 熟知 ， 因 为 它 是 设计 客户 端 -服务 器 应 
用 的 最 佳 方式 。 所 有 最 好 的 Web 框架 都 围绕 MVC 概念 构建 。 虽 然 可 能 引起 激烈 的 争论 ， 但 我 还 是 要 说 ， 不 
使 用 MVC 设计 Web 应 用 是 错误 的 做 法 。 就 概念 层次 而 言 ，MVC 设计 模式 非常 容易 理解 : 


























。 模型 (M) 是 数据 的 表述 。 它 不 是 真正 的 数据 ， 而 是 数据 的 接口 。 使 用 模型 从 数据 库 中 获取 数据 时 ， 
无 需 知道 底层 数据 库 错 综 复 杂 的 知识 。 模 型 通常 还 会 为 数据 库 提供 一 层 抽象 ， 这 样 同一 个 模型 就 能 
用 不 同 的 数据 库 。 

。 视图 (V) 是 你 看 到 的 界面 。 它 是 模型 的 表现 层 。 在 电脑 中 ， 视 图 是 你 在 浏览 器 中 看 到 的 Web 应 用 的 


























1.7 模型 -视图 -控制 器 设计 模式 - 9 











页 面 ， 或 者 是 提 面 应 用 的 UI。 视 图 还 提供 了 收集 用 户 输入 的 接口 。 
控制 模型 和 视图 之 间 的 信息 流动 。 它 通过 程序 逻辑 判断 通过 模型 从 数据 库 中 获取 什么 信 


。 控制 器 (C) 





息 ， 以 及 把 什么 信息 传 给 视 





























图 。 它 还 通过 视 





或 者 通过 模型 修改 数据 ， 或 者 二 者 兼 具 。 











真正 让 人 困惑 的 是 如 何 理 解 各 层 的 作用 ， 不 同 的 机 





























家 ”可 能 会 说 某 个 函 











Django 严格 遵守 M 





型 、 模 板 和 视图 中 ， 因 此 Django 经 常 被 称 为 MTV 相 


。 M 表示 “模型 *， 即 数据 访问 层 。 这 一 层 包 含 所 有 与 数据 相关 的 功能 : 
式 、 数 据 的 行为 、 数 据 之 间 的 关系 。 第 4 章 将 深入 探讨 Django 的 模型 。 


了 表示 “模板 
西 。 第 3 章 







































































图 从 用 户 那里 收集 信息 ， 并 且 实 现 业 务 逻 辑 : 变更 视图 

















数 属于 视图 ， 另 一 个 专家 可 能 强烈 反对 ， 沉 得 应 该 放 在 控制 器 中 。 


对 于 真正 做 事 的 程序 员 来 说 ， 我 们 无 需 关 心 这 个 问题 ， 因 为 完全 没关系 。 只 要 理解 Django 实现 MVC 模式 的 
方式 ， 我 们 就 能 自由 运用 ， 把 工作 做 好 。 不 过 ,在 讨论 组 中 看 人 激烈 争论 是 打发 无 聊 的 不 错 方式 .…… 


























VC 模式, 但 是 有 自己 的 实现 逻辑 。“C” 部 分 由 框架 处 理 ， 多 数 时 候 ， 我 们 的 工作 在 模 








E 架 。 在 MTV 开发 模式 中 : 









































”， 即 表现 层 。 这 一 层 包 含 表现 相关 的 决策 : 在 网 页 或 其 他 文档 类 型 中 如 何 显示 某 个 东 


入 探讨 Django 的 模板 。 











。 YV 表示 “视图 


”， 即 业务 逻辑 层 。 这 一 











a 


E 架 往往 会 使 用 不 同 的 方式 实现 同样 的 功能 。 一 个 框架 “ 专 


访问 数据 的 方式 、 验 证 数据 的 方 


层 包含 访问 模型 和 选择 合适 模板 的 逻辑 。 你 可 以 把 视图 看 做 模型 


和 模板 之 间 的 桥梁 。 下 一 章 将 讨论 Django 的 视 





在 名 称 的 使 用 上 ， 这 可 能 是 Django 唯一 的 不 足 ， 因 为 
视图 是 Django 中 的 模板 。 乍 一 看 有 点 难以 理解 ， 不 过 
Django 的 人 才 应 该 深究 。 当 然 ， 喜 欢 叫板 的 人 也 是 。 





1.8 接 下 来 

















图 。 











Django 的 视图 更 像 是 MVC 中 的 控制 器 ， 而 MVC 


的 











作为 做 事 的 程序 员 来 说 ， 无 需 纠 结 这 个 问题 。 教 授 


我 们 已 经 安装 了 所 需 的 一 切 ， 而 且 运 行 了 开发 服务 器 ， 接 下 来 转向 Django 的 视图 ， 学 习 使 用 Django 伺服 网 


页 的 基础 知识 。 
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第 2 章 视图 和 URL 配置 





前 一 章 说 明了 如 何 创建 Django 项 目 ， 以 及 如 何 运 行 Django 开发 服务 器 。 本 章 学 习 使 用 Django 创建 动态 网 页 
的 基础 知识 。 








2.1 第 一 个 Django 驱动 的 页 面 ，Hello World 











首先 ， 我 们 来 创建 一 个 网 页 ， 输 出 著名 的 示例 消息 :“Hello World”。 如 果 不 使 用 Web 框架 ， 你 可 以 直接 在 
个 文本 文件 中 输入 “Hello World”， 把 它 命 名 为 hello.html， 然 后 上 传 到 Web 服务 器 中 的 某 个 目录 里 。 注 意 ， 
在 这 个 过 程 中 要 为 那个 网 页 指定 两 个 重要 信息 : 网 页 的 内 容 (字符 串 "Hello world") 和 URL (如 

http://www.example.com/hello.html) 。 在 Django 中 也 要 指定 这 两 个 信息 ， 但 是 方式 不 同 。 页 面 的 内 容 由 视 
图 函数 (view function) 生成 ，URL 在 URL 配置 (URLconf) 中 指定 。 先 来 编写 生成 “Hello World” 的 视图 函 


























































































































2.1.1 第 一 个 视图 























在 前 一 章 创 建 的 mysite 目录 中 新 建 一 个 空 文件 ， 名 为 views.py。 这 个 模块 用 于 保存 本 章 编写 的 视图 。 生 成 
“Hello World” 的 视图 很 简单 。 下 面 是 完整 的 视图 函数 ， 以 及 导入 语句 。 请 把 下 述 代码 输入 到 views.py 文件 
中 。 















































from django.http import HttpResponse 


def hello(request): 
return HttpResponse("Hello world") 


我 们 来 逐 行 分 析 一 下 这 上段 代码 : 





。 首先 ， 从 django.http 模块 中 导入 HttpResponse 类 。 导 人 这 个 类 是 因为 后 面 的 代码 要 使 用 。 

。 然后 ， 定 义 一 个 名 为 hello 的 函数 ， 这 是 视图 函数 。 视 图 函数 至 少 有 一 个 参数 ， 按 约定 ， 名 为 re- 
quest。 这 是 一 个 对 象 ， 包 含 触发 这 个 视图 的 Web 请 求 的 信息 ， 是 django.http.HttpRequest 类 的 实 
例 。 









































这 里 ， 我 们 没有 用 到 request， 但 是 必须 作为 第 一 个 参数 传 给 视图 。 注 意 ， 视 图 函数 的 名 称 没 有 关系 ， 无 需 
使 用 特定 的 方式 命名 ，Django 能 识别 它 。 我 们 把 这 个 视图 命名 为 heLLo， 因 为 这 个 名 称 能 明确 表明 视图 的 作 
用 。 如 果 愿 意 ， 也 可 以 命名 为 heLLo_wonderfuL_beautifuL_worLd， 或 其 他 任何 名 称 。2.1.2 市 会 说 明 Django 
查找 这 个 函数 的 方式 。 


这 个 函数 的 定义 体 只 有 一 行 代码 : 返回 使 用 文本 "Hello world" 实例 化 的 HttpResponse 对 象 。 
























































这 里 的 主要 知识 点 是 ， 视 图 就 是 普通 的 Python 函数 ， 它 的 第 一 个 参数 是 HttpRequest 对 象 ， 返 回 值 是 一 个 
HttpResponse 实例 。Python 函数 要 想 变 成 Django 视图 ， 必 须 做 这 两 件 事 。 (也 有 例外 ， 后 文 说 明 。) 
































2.1.2 第 一 个 URL 配置 











如 果 现 在 运行 python manage.py runserver， 看 到 的 仍然 是 “Welcome to Django” 消 息 ，“Hello World” 视 图 完全 









































没有 踪影 。 这 是 因为 mysite 项 目 还 不 知道 有 hetto 视图 的 存在 ， 我 们 要 明确 告诉 Django 在 某 个 URL 上 激活 
这 个 视图 。 还 以 发 布 静态 HTML 文件 为 例 说 明 ， 现 阶段 相当 于 创建 好 了 HTML 页 面 ， 但 是 还 没有 把 它 上 传 
到 服务 器 中 的 某 个 目录 里 。 









































若 想 把 视图 函数 与 特定 的 URL 对 应 起 来 ， 要 使 用 URL 配置 (URLconf) 。URL 配置 相当 于 Django 驱动 的 网 
站 的 目录 。 简 单 来 说 ，URL 配置 把 URL 映射 到 相应 的 视图 函数 上 。 我 们 以 这 种 方式 告诉 Django,“ 访 问 这 个 
URL 时 调用 这 些 代码 ， 访 问 那个 URL 时 调用 那些 代码 ”。 



























































例如 ， 有 人 访问 /foo/ 这 个 URL 时 ， 调 用 views.py 模块 中 的 foo_view() 视图 函数 。 前 一 章 执行 djangoadmin 
startproject 时 自动 创建 了 一 个 URL 配置 urls.py 文件 。 


这 个 文件 的 默认 内 容 如 下 所 示 : 




















Wn 


mysite URL Configuration 


The urlpatterns list routes URLs to views. For more information please see: 
https://docs.djangoproject.com/en/1.8/topics/http/urls/ 
Examples: 
Function views 
1. Add an import: from my_app import views 
2. Add a URL to urlpatterns: url(r'^$', views.home, name='home') 
Class-based views 
1. Add an import: from other_app.views import Home 
2. Add a URL to urlpatterns: url(r'^$', Home.as_view(), name='home') 
Including another URLconf 
1. Add an import: from blog import urls as blog_urls 
2. Add a URL to urlpatterns: url(r'^blog/', include(blog_urls)) 
from django.conf.urls import include, url 
from django.contrib import admin 


urlpatterns = [ 
url(r'^admin/', include(admin.site.urls)), 


] 
把 文件 项 部 的 文档 注释 去 掉 ， 剩 下 的 是 URL 配置 的 精华 : 








from django.conf.urls import include, url 
from django.contrib import admin 


urlpatterns = [ 
url(r'^admin/', include(admin.site.urls)), 


] 
我 们 来 逐 行 分 析 这 上 段 代 码 : 
。 第 一 行 从 django.conf.urls 模块 中 导入 两 个 函数 : include， 用 于 导入 男 一 个 URL 配置 模块 ，urL， 使 
用 正则 表达 式 模式 匹配 浏览 器 中 的 URL， 把 它 映 射 到 Django 项目 中 的 某 个 模块 上 。 


。 第 二 行 从 django.contrib 模块 中 导入 admin 男 数 。 这 个 函数 传 给 include 函数 ， 加 载 Django 管理 后 台 
的 URL。 


。 第 三 行 是 urLpatterns， 即 urL() 实例 列表 。 












































这 里 主要 要 注意 的 是 urtpatterns 变量 ，Django 期 望 URL 配置 模块 中 有 这 个 变量 。 它 负责 定义 URL 与 处 理 
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URL 的 代码 之 间 的 映射 。 在 URL 配置 中 添加 URL 和 视 








hello 视图 的 方式 如 下 : 











from django.conf.urls import include, url 


from django.contrib import admin 
from mysite.views import hello 


urlpatterns = [ 
url(r'^admin/', include(admin.site.urls)), 


] 


url(r'^hello/$', hello), 


我 们 做 了 两 处 修改 : 





首先 ， 从 mysite/views.py (在 Python 导入 句法 中 要 使 


























定 mysite/views.py 在 Python 路 径 中 。) 
然后 ， 把 urt(r'^hello/$'，hello), 这 行 代码 添加 到 urtpatterns 中 。 我 们 添加 的 这 行 代码 称 为 一 个 





URL 模式 (URLpattern) 。urtL() 函数 告诉 Django 如 何 处 到 





图 的 方式 是 ， 把 URL 模式 映射 到 视图 函数 上 。 添 加 





mysite.views) 模块 中 导入 hello 视图 。 ( 假 

















我 们 配置 的 URL。 第 一 个 参数 是 模式 匹配 














字符 串 〈 一 个 正则 表达 式 ， 稍 后 说 明 ) ， 第 二 个 参数 是 模式 使 用 的 视图 函数 。urt() 还 有 一 个 可 选 参 


数 ， 在 第 7 章 详 述 。 




















这 里 还 有 一 个 重要 的 细节 : 正则 表达 式 字符 串 前 面 的 'r' 字符 。 它 的 目的 是 告诉 Python， 那 是 “原始 字符 
串 "， 不 要 解释 里 面 的 反 斜 线 。 


在 常规 的 Python 字符 是 
果 添 加 r， 标 记 为 原始 字符 串 ，Python 不 会 转 义 ， 因 出 











一 个 是 小 写字 母 m。 


Python 中 的 反 和 斜 线 与 了 


串 。 


综 上 ， 我 们 告诉 Django， 对 /hello/ URL 的 请 求 应 该 








URL 模式 的 句法 需要 说 明 一 下 ， 
想象 中 有 点 区 别 。 原 因 如 下 : 





E 则 表达 式 





FP 的 反 和 斜 线 有 冲突 ， 


因为 你 或 许 





























中 ， 反 斜 线 用 于 转 义 特殊 的 字符 ， 例 如 "\n" 这 个 字符 串 是 一 个 字符 ， 表 示 换行 。 如 
t，"r'\n'" 是 两 个 字符 组 成 的 字符 串 ， 一 个 是 反 斜 线 ， 


因此 在 Django 中 定义 正则 表达 式 时 最 好 使 用 原始 字符 





| hello 视图 函数 处 理 。 


不 能 立即 理解 。 我 们 想 匹 配 的 是 /hetllo/ URL， 但 是 用 的 模式 与 


。 Django 在 检查 URL 模式 时 会 把 人 站 URL 前 面 的 斜 线 去 掉 。 因 此 ，URL 模式 中 没有 前 导 和 斜 线 。 一 开始 
可 能 觉得 这 不 符合 直觉 ， 但 是 这 样 做 能 简化 一 些 事情 ， 例 如 把 URL 配置 引入 其 他 URL 配置 (参阅 第 


7 章 ) 。 





模式 中 包含 一 个 脱 字符 号 








(^) 和 一 个 美元 符号 ($) 。 


























它们 在 正则 表达 式 中 有 特殊 的 意义 : 脱 字符 号 





表示 "在 字符 串 的 开头 匹配 模式 ”， 美 元 符号 的 意思 是 “在 字符 串 的 结尾 匹配 模式 ”。 











这 个 概念 最 好 通过 实例 说 明 。 如 果 使 用 “hello/ 模式 (末尾 没 





























美元 符号 ) ， 那 么 任何 以 /heLto/ 开 











头 的 URL 字符 串 都 能 匹配 ， 例 如 /hello/foo 和 /hello/bar， 而 不 只 是 /hello/。 
类 似 地 ， 如 果 开 头 没 有 脱 字符 号 ( 即 hello/$) ，Django 会 匹配 任何 以 hello/ 结尾 的 URL, 例如 

















/foo/bar/hello/, 
如 果 只 使 用 hello/， 没 











了 脱 字 符号 或 美元 符号 ， 那 么 作 











Lo/bar。 
因此 ， 我 们 使 


























j 脱 字符 号 和 美元 符号 确保 只 匹配 /hello/ 这 个 URL 一 一 不 多 不 少 。 











都 以 脱 字符 号 开头 、 以 美元 符 

















尾 ， 不 过 可 以 灵活 使 用 ， 








E 何 包含 hello/ 的 URL 都 匹配 ， 例 如 /foo/hel- 


大 多 数 URL 模式 
匹配 复杂 的 URL。 





你 可 能 想 知道 ， 如 果 有 人 请 求 /hetllo URL (末尾 没有 和 斜 线 ) 会 发 生 什么 。 因 为 我 们 指定 的 URL 模式 要 求 有 





末尾 的 斜 线 ， 








因此 那个 URL 不 匹配 。 然 而 ， 黑 认 情 况 下 ， 如 果 请 求 的 URL 不 匹配 任何 URL 模式 ， 而 且 末 尾 





2.1 第 一 个 Django 驱动 的 页 面 ，Hello World - 13 





没有 斜 线 ， 那 么 Django 会 把 它 重 定向 到 末尾 带 斜 线 的 URL。 (这 个 行为 由 Django 的 APPEND_SLASH 设置 管 
理 ， 参 见 附录 D。) 


关于 这 个 URL 配置 ， 还 有 一 件 事 要 注意 : 我 们 以 对 象 的 形式 传人 hello 视图 函数 ， 而 没有 调用 函数 。 这 是 
Python (以 及 其 他 动态 语言 ) 的 一 个 关键 特性 : 函数 是 一 等 对 象 ， 可 以 像 其 他 变量 那样 传递 。 很 棒 吧 | 


























为 了 测试 对 URL 配置 的 更 改 ， 像 第 1 章 那样 启动 Django 开发 服务 器 : 运行 python manage.py runserver 命 
令 。 (如 果 开 发 服务 器 一 直 运 行 着 也 没关系 ， 它 能 自动 检测 到 Python 代码 的 变化 ， 按 需 重新 加 载 ， 因 此 改动 
后 无 需 重启 服务 器 。) 开发 服务 器 运行 在 http://127.0.0.1:8900/ 地 址 上 ， 因 此 要 在 Web 浏览 器 中 访问 
http://127.0.0.1:8000/hello/。 你 应 该 能 看 到 文本 “Hello World”， 即 那个 Django 视图 的 输出 (图 2-1) 。 

















口 127.0.0.1:8000/hello/ x 
< G 省 口 127.0.0.1:8000/hello enwO 轴 三 
Hello World 


图 2-1， 好 耶 ! 我 们 的 第 一 个 Django 视图 


2.1.3 正则 表达 式 


正则 表达 式 (regular expression， 简 称 regexes) 是 指定 文本 模式 的 简洁 方式 。Django 的 URL 配置 允许 使 用 任 
何 正 则 表达 式 匹 配 复杂 的 URL， 但 是 实际 上 只 会 使 用 部 分 符号 。 表 2-1 列 出 了 常用 的 符号 。 


表 2-1， 常 用 的 正则 表达 式 符号 





















































符号 匹配 的 内 容 
(点 号 ) 单个 字符 
\d 单个 数字 
[A-Z] A-Z (大 写 ) 之 间 的 单个 字母 
[a-z] a-z (小 写 ) 之 间 的 单个 字母 
[A-Za-z] a-z (不 区 分 大 小 写 ) 之 间 的 单个 字母 





14- 第 2 章 视图 和 URL 配置 


( 续 ) 











符号 匹配 的 内 容 

+ 一 个 或 多 个 前 述 表 达 式 (例如 ，\d+ 匹配 一 个 或 多 个 数字 ) 

[/]+ 一 个 或 多 个 字符 ， 直 到 遇 到 和 斜 线 (不 含 ) 

? 零 个 或 一 个 前 述 表达 式 (例如 ，\d? 匹配 零 个 或 一 个 数字 ) 

零 个 或 多 个 前 述 表达 式 (例如 ，\d* 匹配 零 个 、 一 个 或 多 个 数字 ) 

和 介 于 一 个 到 三 个 之 间 ( 含 ) 的 前 述 表 达 式 (例如 ，\d{1,3} 匹配 一 个 、 两 个 或 三 个 


数字 ) 








正则 表达 式 的 详细 说 明 参 阅 Python 正则 表达 式 文档 。 





2.1.4 关于 404 错误 的 简要 说 明 





i 








现在 ，URL 配置 只 定义 了 一 个 URL 模式 ， 即 处 理 /hello/ URL 请 求 的 那个 。 那 么 ， 如 果 请 求 其 他 URL 会 发 
生 什 么 呢 ? 为 了 查 明 ， 启 动 Django 开发 服务 器 ， 然 后 访问 http://127.0.0.1:8000/goodbye/。 你 应 该 会 看 到 











“Page not found” 消 息 (图 2-2) 。Django 之 所 以 显示 这 个 消息 ， 是 因为 URL 配置 中 没有 定义 你 请 求 的 URL。 


DD Page not found at /goodt X 


和 





@ 人 骆 | 口 127.0.0.1:8000/goodbjye QIO 员 三 


Page not found (4o4) 


Request Method: GET 
Request URL: http://127.0.0.1:8000/goodbye/ 


Using the URLconf defined in mysite.urls, Django tried these URL patterns, in 
this order: 


1. ^admin/doc/ 
2. ^admin/ 
3. ^hello/$ 


The current URL, goodbye/, didn't match any of these. 


You're seeing this error because you have DEBUG = True in your Django settings 
file. Change that to False, and Django will display a standard 404 page. 


图 2-2，Django 的 404 页 面 


这 个 页 面 除了 显示 404 错误 消息 之 外 ， 还 给 出 了 其 他 信息 。 它 会 告诉 你 Django 使 用 的 是 哪个 URL 配置 ， 以 
及 那个 配置 里 的 各 个 模式 。 根 据 这 些 信息 你 应 该 能 判断 为 什么 所 请 求 的 URL 会 返回 404 错误 。 














显然 ， 这 些 是 敏感 信息 ， 只 供 Web 开发 者 查看 。 线 上 网 站 不 应 该 公开 显示 这 些 信息 。 鉴 于 此 ，“Page not 





found" 页 面 仅 当 Django 项 目 处 于 调试 模式 时 才 会 显示 。 





2.1 第 一 个 Django 驱动 的 页 面 ，Hello World - 15 





后 文 会 说 明 如 何 解除 调试 模式 。 现 在 ， 你 只 需 知道 ， 创 建 Django 项 目 后 ， 它 就 处 于 调试 模式 。 如 果 不 在 调试 
模式 中 ，Django 会 输出 其 他 的 404 响应 。 





2.1.5 关于 网 站 根 地 址 的 简要 说 明 





据 前 一 节 所 述 ， 如 果 访 问 网 站 根 地 址 (http://127.0.0.1:8000/) ， 你 会 看 到 一 个 404 错误 消息 。Django 不 
会 自作 主张 在 网 站 根 地 址 上 添加 页 面 一 一 根 地 址 没什么 特别 的 。 


你 要 像 URL 配置 中 的 其 他 条 目 一 样 ， 为 根 地 址 指定 一 个 URL 模式 。 匹 配 网 站 根 地 址 的 URL 模式 不 太 直 观 ， 
需要 说 明 一 下 。 


准备 为 网 站 根 地 址 实现 视图 时 ， 使 用 的 URL 模式 是 $， 即 匹配 空 字符 串 。 例 如 : 






































from mysite.views import hello, my_homepage_view 
urlpatterns = [ 


url(r'^$', my_homepage_view), 
鞭 


2.1.6 Django 处 理 请 求 的 过 程 





继续 编写 第 二 个 视图 函数 之 前 ， 我 们 停 一 下 ， 稍 微 了 解 Django 的 运作 机 制 。 你 在 Web 浏览 器 中 访问 
http://127.0.0.1:8000/hello/， 看 到 “Hello world”* 消 息 ， 在 这 个 过 程 中 Django 在 背后 做 了 什么 呢 ? 一 切 都 从 
设置 文件 开始 。 




















运行 python manage.py runserver 命令 时 ，manage.py 脚本 在 内 层 mysite 目录 中 寻找 名 为 settings.py 的 文 
件 。 这 个 文件 中 保存 着 当前 Django 项 目的 全 部 配置 ， 各 个 配置 的 名 称 都 是 大 写 的 ， 例 如 TEMPLATE_DIRS、 
DATABASES， 等 等 。 其 中 最 重要 的 设置 是 ROOT_URLCONF。 它 告诉 Django， 网 站 的 URL 配置 在 哪个 Python 模块 
中 。 
































记得 吗 ? 运行 django-admin startproject 命令 时 创建 了 settings.py 和 urls.py 文件 。 自 动 生成 的 set- 
tings.py 文件 中 包含 ROOT_URLCONF 设置 ， 指 向 自动 生成 的 urls.py 文件 。 打 开 settings.py 文件 ， 你 自己 看 
一 下 。 应 该 会 看 到 下 述 设置 ， 








ROOT_URLCONF = 'mysite.UrtLs' 


这 个 模块 对 应 的 文件 是 mnysite/urts.py。 收 到 针对 某 个 URL (假如 是 /hello/) 的 请 求 时 ，Django 加 载 
ROOT_URLCONF 设置 指定 的 URL 配置 ， 然 后 按 顺 序 检查 URL 配置 中 的 各 个 URL 模式 ， 依 次 与 请 求 的 URL 比 
较 ， 直 到 找到 匹配 的 模式 为 止 。 


找到 匹配 的 模式 之 后 ， 调 用 对 应 的 视图 函数 ， 并 把 一 个 HttpRequest 对 象 作为 第 一 个 参数 传 给 视图 。 (后 文 
会 详 述 HttpRequest。) 如 我 们 编写 的 第 一 个 视图 所 示 ， 视 图 函数 必须 返回 一 个 HttpResponse 对 象 。 











































































































随后 ， 余 下 的 工作 交 给 Django 处 理 : 把 那个 Python 对 象 转换 成 正确 的 Web 啊 应 ， 并 且 提 供 合适 的 HTTP 首 
部 和 主体 〈 即 网 页 的 内 容 ) 。 综 上 : 




















1. 请求 /hello/。 
Django 查看 ROOT_URLCONF 设置 ， 找 到 根 URL 配置 。 

Django 比较 URL 配置 中 的 各 个 URL 模式 ， 找 到 与 /heltlo/ 匹配 的 那个 。 
如 果 找 到 匹配 的 模式 ， 调 用 对 应 的 视图 函数 。 

视图 函数 返回 一 个 HttpResponse 对 象 。 
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6. Django 把 HttpResponse 对 象 转换 成 正确 的 HTTP 响应 ， 得 到 网 页 。 


























现在 ， 我 们 知道 如 何 编写 Django 驱动 的 页 面 了 。 整 个 过 程 十 分 简单 ， 只 需 编写 视图 函数 ， 然 后 在 URL 配置 






































中 与 URL 配对 。 


2.2 第 二 个 视图 ， 动 态 内 容 











“Hello World "视图 是 为 了 说 明 Django 的 基本 运作 方式 ， 但 那 不 是 动态 网 页 ， 因 为 页 面 的 内 容 始 终 不 变 。 每 











访问 /hello/， 看 到 的 都 是 相同 的 内 容 ， 好 似 一 个 静态 HTML 文件 。 











这 一 次 ， 我 们 要 创建 一 些 动态 内 容 ， 在 网 页 中 显示 当前 日 期 和 时 间 。 这 是 不 错 的 第 二 步 ， 因 为 不 涉及 数据 库 
或 用 户 输入 ， 只 是 输出 服务 器 的 内 部 时 钟 。 这 个 页 面 不 比 "Hello World "强大 多 少 ， 但 是 通过 它 能 说 明 一 些 新 
念 。 这 个 视图 要 做 两 件 事 : 计算 当前 日 期 和 时 间 ， 然 后 返回 包含 那个 值 的 HttpResponse 对 象 。 如 果 用 过 

































































Python， 你 应 该 知道 Python 有 个 datetime 模块 ， 用 于 计算 日 期 。 用 法 如 下 : 














>>> import datetime 

>>> now = datetime.datetime.now() 

>>> now 

datetime.datetime(2015, 7, 15, 18, 12, 39, 2731) 
>>> print (now) 

2015-07-15 18:12:39.002731 











次 





很 简单 ， 而 且 不 用 麻烦 Django。 这 就 是 常规 的 Python 代码 。 (我 会 强调 “常规 的 Python 代码 和 Django 专属 











的 代码 。 在 学 习 Django 的 过 程 中 ,希望 你 能 学 会 把 知识 运用 到 Django 之 外 的 Python 项 目 中 。) 若 想 在 














Django 视图 中 显示 当前 日 期 和 时 间 ， 我 们 只 需 把 datetime.datetime.now() 语句 放 到 一 个 视图 中 ， 然 后 返回 




















一 个 HttpResponse 对 象 。 参 照 下 述 代 码 更 新 views .py: 





from django.http import HttpResponse 
import datetime 


def hello(request): 
return HttpResponse("Hello world") 


def current_datetime(request): 
now = datetime.datetime.now() 
html = "It is now %s." % now 
return HttpResponse(html) 





为 了 理解 current_datetime 视图 ， 下 面 逐 行 分 析 所 做 的 改动 : 


























。 我 们 在 模块 顶部 添加 了 import datetime， 这 样 才能 计算 日 期 。 


。 新 添加 的 current_datetime 函数 计算 当前 日 期 和 时 间 ， 得 到 的 结果 是 一 个 datetime.datetime 对 象 ， 
存储 在 局 部 变量 now 中 。 























。 视图 函数 中 的 第 二 行 代码 使 用 Python 的 格式 字符 串 功能 构建 一 个 HIML 响应 。 字 符 串 中 的 %s 是 占 位 
符 ， 字 符 串 后 面 的 百 分 号 指明 ,“ 把 前 述 字符 串 中 的 %s 替换 成 now 变量 的 值 "。 严 格 来 说 ，now 变量 的 
值 是 一 个 datetime.datetime 对 象 ， 而 非 字 符 串 ， 但 是 %s 格式 字符 会 把 它 转换 成 字符 串 表 示 形 式 ， 得 




















到 的 结果 类 似 于 "2015-07-15 18:12:39.002731"。 最 终 得 到 的 HTML 字符 串 是 这 样 的 : "It is now 
2015-07-15 18:12:39.002731."。 


。 最 后 ， 返 回 包含 那个 HTML 字符 串 的 HttpResponse 对 象 一 一 这 与 hello 视图 所 做 的 一 样 。 


























把 相关 代码 添加 到 views.py 中 之 后 ， 要 在 urls.py 中 添加 URL 模式 ， 告 诉 Django， 哪 个 URL 使 用 这 个 视图 





2.2 第 二 个 视图 ， 动 态 内 容 - 
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处 理 。 这 里 可 以 使 用 /time/。 





from django.conf.urls import include, url 
from django.contrib import admin 
from mysite.views import hello, current_ datetime 


urlpatterns = [ 
url(r'^admin/', include(admin.site.urls)), 
url(r'^hello/$', hello), 
url(r'^time/$', current_datetime), 


] 

















我 们 对 URL 配置 做 了 两 处 改动 。 其 一 ， 在 顶部 导入 了 current_datetime 函数 ， 其 二 ， 这 是 较为 重要 的 ， 添 
加 一 个 URL 模式 ， 把 /time/ URL 喘 射 到 那个 新 视图 上 。 外 bE 理解 吧 ? 编写 视图 并 且 更 新 URL 配置 之 后 ， 运 
行 runserver 命令 ， 然 后 在 浏览 器 中 访问 http://127.0.0.1:8000/time/。 你 应 该 看 到 当前 日 期 和 时 间 。 如 果 
看 到 的 不 是 本 地 时 间 ， 有 可 能 是 因为 在 settings.py 中 把 默认 时 区 设 为 "UTC' 了 。 







































































2.3 URL 配置 和 松 耦 合 


现在 是 个 好 时 机 ， 我 们 要 强调 URL 配置 以 及 Django 背后 的 一 个 重要 哲学 : 松 耦 合 。 简 单 来 说 ， 松 耦合 是 一 
种 软件 开发 方式 ， 其 价值 在 于 让 组 件 可 以 互 换 。 如 果 两 部 分 代码 之 间 是 松 耦 合 的， 那么 改动 其 中 一 部 分 对 另 
一 部 分 的 影响 很 小 ， 甚 至 没有 影响 。 









































Django 的 URL 配置 就 很 好 地 运用 了 这 个 原则 。 在 Django Web 应 用 中 ，URL 定义 与 所 调用 的 视图 函数 之 间 
是 松 耦 合 的 ， 即 某 个 功能 使 用 哪个 URL 与 视图 函数 的 实现 本 身 放 在 两 个 地 方 。 














以 current_datetime 视图 为 例 。 如 果 想 把 这 个 功能 对 应 的 URL 从 /time/ 移 到 /current-time/， 只 需 修改 
URL 配置 ， 视 图 则 不 用 动 。 同 样 ， 对 视图 函数 的 逻辑 所 做 的 修改 对 开放 这 一 功能 的 URL 没有 影响 。 此 外 ， 
如 果 想 在 多 个 URL 上 开放 当前 日 期 功能 ， 可 以 编辑 URL 配置 ， 而 无 需 改动 视图 代码 。 















































在 下 述 示例 中 ，current_datetime 可 以 通过 两 个 URL 访问 。 我 们 是 故意 这 么 做 的 ， 但 是 其 中 涉及 的 知识 能 用 
得 到 。 


urlpatterns = [ 
url(r'^admin/', include(admin.site.urls)), 
url(r'^hello/$', hello), 
url(r'^time/$', current_datetime), 
url(r'^another-time-page/$', current_datetime), 


] 





URL 配置 和 视图 之 间 就 是 松 耦 合 的 。 在 本 书后 续 内 容 中 我 会 不 断 指出 运用 这 个 重要 原则 的 地 方 。 








2.4 第 三 个 视图 ， 动 态 URL 














在 current_datetinme 视图 中 ， 页 面 的 内 容 (当前 日 期 和 时 间 ) 是 动态 的 ， 但 URL 是 静态 的 (/time/) 。 可 

是 ， 在 多 数 动态 Web 应 用 中 ，URL 中 会 包含 参数 ， 影 响 页 面 的 输出 。 比 如 说 ， 在 线 书店 会 为 每 本 书 分 配 一 

个 URL， 例 如 /books/243/ 和 /books/81196/。 下 面 创 建 第 三 个 视图 ， 以 一 定 的 偏 移 量 显示 当前 日 期 和 时 间 。 

我 们 的 目标 是 让 /time/pLus/1/ 页 面 显 示 一 小 时 之 后 的 日 期 和 时 间 ， 让 /time/plus/2/ 页 面 显示 两 小 时 之 后 的 
日 期 和 时 间 ， 让 /time/plus/3/ 页 面 显 示 三 小 时 之 后 的 日 期 和 时 间 ， 以 此 类 推 。 新 手 可 能 想 分 别 为 各 个 偏 移 

量 编写 一 个 视图 函数 ， 然 后 在 URL 配置 中 这 样 定义 模式 : 


















































































































































urlpatterns = [ 
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url(r'^time/$', current_datetinme), 

url(r'^time/plus/1/$', one_hour_ahead), 

url(r'^time/plus/2/$', two_hours_ahead), 

url(r'^time/plus/3/$', three_hours_ahead), 
] 


显然 ， 这 样 想 是 错 的 。 














这 样 做 不 仅 要 重复 编写 视图 函数 ， 而 且 应 用 只 能 支持 预先 定义 的 偏 移 范围 (一 小 时 、 两 小 时 或 三 小 时 ) 。 

















如 果 想 创建 显示 四 小 时 之 后 的 时 间 的 页 面 ， 必 须 再 编写 一 个 视图 ， 并 且 添 加 一 行 URL 配置 一 一 重复 更 多 了 | 






































那么 ， 为 了 处 理 任意 的 偏 移 量 ， 应 该 怎么 设计 应 用 呢 ? 问题 的 关键 是 ， 使 用 通 配 URL 模式 。 前 面 说 过 ，URL 
模式 是 正则 表达 式 ， 因 此 我 们 可 以 使 用 \d+ 模式 匹配 一 个 或 多 个 数字 : 






































urlpatterns = [ 
和 
url(r'^time/plus/\d+/$', hours_ahead), 
和 

] 











(# .的 意思 是 其 他 URL 模式 被 省 略 了 。) 这 个 URL 模式 能 匹配 /time/plus/2/、/time/plus/25/， 其 至 是 
/time/pLus/100000000000/。 但 是 ， 这 么 大 的 偏 移 量 不 太 切 合 实际 ， 我 们 将 为 偏 移 量 设 个 合理 的 最 大 值 。 


这 里 ， 我 们 想 把 最 大 偏 移 量 设 为 99 小 时 ， 因 此 要 限制 只 能 使 用 一 个 或 两 个 数字 。 使 用 正则 表达 式 句法 来 表 
示 ， 就 是 \d{1,2}: 
































url(r'^time/plus/\d{1,2}/$', hours_ahead), 








现在 ， 我们 配置 好 了 通 配 URL， 下 面 要 把 通 配 数 据 传 给 视图 函数 ， 以 便 在 一 个 视图 函数 中 人 处理 任意 的 偏 移 
量 。 为 此 ， 我 们 在 URL 模式 中 放 一 对 圆 括号 ， 把 想 保 存 的 数据 括 起 来 。 在 这 个 示例 中 ， 我 们 要 保存 URL 中 
的 数字 ， 因 此 要 在 \d{1,2} 两 侧 放 置 圆 括 号 ， 如 下 所 示 : 

















url(r'^time/plus/(\d{1,2})/$', hours_ahead), 

















如 果 你 熟悉 正则 表达 式 ， 应 该 能 理解 这 么 做 的 作用 ， 我 们 使 用 圆 括号 从 匹配 的 文本 中 捕获 数据 。 最 终 的 URL 
配置 ， 以 及 前 面 两 个 视图 的 配置 ， 如 下 所 示 : 









































from django.conf.urls import include, url 
from django.contrib import admin 
from mysite.views import hello, current_ datetime, hours_ahead 
urlpatterns = [ 
url(r'^admin/', include(admin.site.urls)), 
url(r'^hello/$', hello), 
url(r'^time/$', current_datetime), 
url(r'^time/plus/(\d{1,2})/$', hours_ahead), 
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如 果 你 用 过 其 他 Web 开发 平台 ， 可 能 会 想 , “使 用 查询 字符 串 参 数 吧 ! ”， 比 如 /time/ 
plus?hours=3; 此 时 ， 偏 移 量 通过 URL 的 查询 字符 串 获取 (? 之 后 的 部 分 ) 。 

















在 Django 中 也 能 这 么 做 〈 详 情 参 见 第 7 章 ) ,但 是 Django 的 核心 哲学 之 一 是 ，URL 应 该 美 
观 。/time/plus/3/ 这 样 的 URL 更 加 简洁 明了 ， 更 加 易于 阅读 ， 更 加 易于 大 声 读 出 来 …… 而 且 
比 使 用 查询 字符 串 的 版 本 美观 得 多 。 美 观 的 URL 是 高 质量 Web 应 用 的 一 个 特色 。Django 的 
URL 配置 系统 鼓励 使 用 美观 的 URL， 而 且 为 此 提供 了 简易 的 方式 。 








设 好 URL 之 后 ， 下 面 编写 hours_ahead 视图 。 这 个 视图 与 前 面 编写 的 current_datetime 视图 很 像 ， 唯 有 一 处 
不 同 : 要 接收 额外 的 参数 ， 即 偏 移 的 小 时 数 。hours_ahead 视图 的 代码 如 下 : 


from django.http import Http404, HttpResponse 
import datetime 


def hours_ahead(request, offset): 

EFY: 

offset = int(offset) 
except ValueError: 

raise Http404() 
dt = datetime.datetime.now() + datetime.timedelta(hours=offset) 
html = "In %s hour(s), it will be %s. 

" % (offset, dt) 

return HttpResponse(html) 


下 面 来 分 析 这 段 代码 。 
hours_ahead 视图 函数 有 两 个 参数 : request 和 offset。 
。 request 是 一 个 HttpRequest 对 象 ， 这 与 hello 和 current_datetime 两 个 视图 一 样 。 我 要 再 次 强调 ， 每 


个 视图 的 第 一 个 参数 都 是 HttpRequest 对 象 。 


。 offset 是 URL 模式 中 那 对 圆 括 号 捕获 的 字符 串 。 如 有 果 请 求 的 URL 是 /time/plus/3/， 那 么 偏 移 量 是 字 
符 串 '3'， 如 果 请 求 的 URL 是 /time/ptus/21/， 那 么 偏 移 量 是 字符 串 '21' 。 注 意 ， 捕 获 的 值 始终 是 
Unicode 对 象 ， 而 不 是 整数 ， 即 便 捕获 的 字符 串 中 只 有 数字 (如 '21' ) 也 不 是 。 






































我 决定 把 那个 变量 命名 为 offset， 不 过 你 可 以 根据 自己 的 喜好 命名 ， 只 要 是 有 效 的 Python 标识 符 就 行 。 变 量 
使 用 什么 名 称 没 关系 ， 重 要 的 是 要 作为 第 二 个 参数 ( 放 在 request 之 后 ) 传 给 视图 函数 。 (除了 位 置 参数 之 
外 ，URL 配置 还 可 以 使 用 关键 字 参 数 。 详 情 参见 第 7 音 。) 














在 视图 函数 中 ， 我 们 首先 调用 int() 处 理 offset。 这 人 么 做 的 目的 是 把 Unicode 字符 串 转 换 成 整数 。 





注意 ， 如 果 传 给 int() 函数 的 值 不 能 转换 成 整数 (如 字符 串 "foo") ，Python 会 抛 出 ValueError 异常 。 在 这 
个 示例 中 ， 如 果 遇 到 ValueError 异常 ， 我 们 抛 出 django.http.Http404 异常 ， 显 示 “Page not found”404 错误 
(你 可 能 猜 到 了 ) 。 


聪明 的 读者 可 能 会 想 ， 怎 么 可 能 出 现 ValueError 呢 ? 毕竟 URL 模式 中 的 正则 表达 式 ((\d{1,2})) 只 能 捕获 
数字 ， 因 此 offset 变量 的 值 只 可 能 是 由 数字 组 成 的 字符 串 。 管 案 是 ， 无 法 保证 。URL 模式 提供 的 输入 验证 
虽然 有 用 ， 但 是 并 不 严谨 ， 因 此 我 们 要 在 视图 函数 中 检查 会 不 会 抛 出 ValueError 异常 ， 以 防 意 外 。 实 现 视 图 
函数 时 最 好 别 对 参数 做 任何 假设 。 松 耦合 ， 还 记得 吗 ? 


























视图 函数 的 下 一 行 计算 当前 日 期 和 时 间 ， 并 且 加 上 相应 的 偏 移 量 。current_datetime 视图 用 过 date- 
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time.datetime.now(); 这 里 的 新 知识 是 ， 表 示 日 期 和 时 间 的 两 个 datetime.datetime 对 象 可 以 做 算术 运算 。 
我 们 把 计算 结果 存储 在 dt 变量 中 。 























这 一 行 还 表明 了 调用 int() 处 理 offset 的 原因 : datetime.timedelta 的 hour 参数 必须 是 整数 。 








接 下 来 ， 与 current_datetime 视图 一 样 ， 构 建 这 个 视图 函数 的 HTML 输出 。 与 之 前 不 同 的 是 ， 这 里 使 用 的 
Python 格式 字符 串 能 处 理 两 个 值 ， 而 不 是 一 个 。 因 此 ， 格 式 字 符 串 中 有 两 个 %s 符号 ， 而 且 要 插入 的 值 是 一 
个 元 组 : (offset，dt)。 


























最 后 ， 返 回 包含 那个 HIML 的 HttpResponse 对 象 。 








视图 函数 写 好 了 ，URL 也 配置 好 了 ， 现 在 启动 Django 开发 服务 器 (如果 没 在 运行 中 ) ， 然 后 访问 
http://127.0.0.1:8000/time/plus/3/， 确认 是 否 正常 。 
































然后 访问 http://127.0.0.1:8000/time/plus/5/。 


再 访问 http://127.0.0.1:8000/time/plus/24/。 














最 后 ， 访 问 http://127.9.6.1:8666/time/plus/109/， 确 保 URL 配置 中 的 模式 只 能 匹配 一 个 或 两 个 数字 。 此 
时 ，Django 应 该 显示 “Page not found" 页 面 ， 与 2.1.4 节 看 到 的 一 样 。 
































http://127.0.0.1:8000/time/plus/ (没有 偏 移 量 ) 也 应 该 返回 404 错误 。 




















2.5 Django 精美 的 错误 页 面 


花 点 时 间 欣 赏 一 下 我 们 构建 的 这 个 Web 应 用 .…… 然 后 ， 搞 点 破坏 。 我 们 要 把 hours_ahead 视图 中 offset = 
int(offset) 那 几 行 注释 掉 ， 故 意 在 views.py 文件 中 引入 一 个 Python 错误 : 





def hours_ahead(request, offset): 
# try: 
# offset = int(offset) 
# except ValueError: 
# raise Http404() 
dt = datetime.datetime.now() + datetime.timedelta(hours=offset) 
html = "In %s hour(s), it will be %s. 
" % (offset, dt) 
return HttpResponse(html) 





启动 开发 服务 器 ， 然 后 访问 /time/plus/3/。 你 会 看 到 一 个 错误 页 面 ， 里 面 有 相当 多 的 信息 ， 包 括 最 顶部 显示 
的 TypeError 消息 : "unsupported type for timedelta hours component: str" (图 2-3) 。 
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BD TypeError at /time/plus/3/ Xx 


€ CG 全 | 四 127.0.0.1:8000/time/plus/3 Qo O 引 = 


TypeError at /time/plus/3/ 


unsupported type for timedelta hours component: str 


Request Method: GET 
Request URL: http://127.0.0.1:8000/time/plus/3/ 
Django Version: 1.9.7 
Exception Type: TypeError 
Exception Value: unsupported type for timedelta hours component: str 


Exception Location: C:\Users\NigeN\OneDrive\Documents\Visual Studio 
2015\Projects\mysite\mysite\mysite\views.py in hours_ahead, line 22 


Python Executable: C:\Users\NigeN\OneDrive\Documents\Visual Studio 
2015\Projects\imysite\mysite\env\Scripts\python.exe 


Python Version: 3.4.3 


Python Path: ['C:\\Users\\Nigel\\OneDrive\\Documents\\Visual Studio ' 
"2815\\Projects\\mysite\\mysite', 
*C:\\WINDOWS\\SYSTEM32\\python34.zip’, 
‘C:\\Users\\Nigel\\OneDrive\\Documents\\Visuyal Studio " 
"2815\\Projects\\mysite\\mysite\\env\\DLLs', 
'C:\\Users\\Nigel\\OneDrive\\Documents\\Visyal Studio ' 
"2815\\Projects\\mysite\\mysite\\env\\1ib’, 
'C:\\Users\\Nigel\\OneDrive\\Documents\\Visual Studio ' 
"2815\\Projects\\mysite\\mysite\\env\\Scripts', 
‘C:\\Python34\\Lib’, 

'C:\\Python34\\DLLs', 
'C:\\Users\\Nigel\\OneDrive\\Documents\\Visual Studio ' 
"2815\\Projects\\mysite\\mysite\\env', 
'C:\\Users\\Nigel\\OneDrive\\Documents\\Visual Studio ' 
"2815\\Projects\\mysite\\mysite\\env\\lib\\site-packages'] 


Server time: Tue,7 Jun 2016 15:45:31 +1000 


Traceback switch to copy-and-paste view 





| » 


图 2-3，Django 的 错误 页 面 


怎么 回 事 ? datetime.timedeLta 函数 期 望 hours 参数 是 整数 ， 而 把 offset 转换 成 整数 的 代码 被 我 们 注释 掉 
了 。 因 此 ，datetime.timedetLta 抛 出 TypeError 异常 。 这 种 小 问题 每 个 程序 员 都 会 遇 到 。 








这 个 示例 的 目的 是 说 明 Django 的 错误 页 面 。 花 点 时 间 浏 览 错 误 页面 ， 熟 悉 它 给 出 的 各 部 分 信息 。 值 得 关注 的 
言 息 有 : 





。 页 面 顶部 是 异常 的 关键 信息 : 异常 的 类 型 和 消息 (这 里 是 "unsupported type") ， 抛 出 异常 的 文件 ， 
以 及 所 在 的 行 号 。 

。 关键 信息 下 面 是 异常 的 完整 Python 调用 跟踪 。 这 与 Python 命令 解释 器 给 出 的 标准 调用 跟踪 类 似 ， 不 
过 能 与 之 交互 。 对 栈 里 的 每 一 层 〈《“ 帧 "” ，Django 都 会 显示 文件 名 、 函 数 /方法 名 、 行 号 和 那 一 行 的 源 
码 。 

。 点 击 源码 所 在 的 行 ( 深 灰 色 ) ， 会 显示 前 后 数 行 ， 提供 上 下 文 。 点 击 每 一 帧 下 面 的 “Local vars” 可 
以 查看 那 一 帧 抛 出 异常 时 所 有 局 部 变量 及 其 值 。 这 些 信 息 能 给 调试 提供 极 大 的 帮助 。 


。 注意 “Traceback”" 标 题 劳 边 的 “Switch to copy-and-paste view” 文 本 。 点 击 那 些 文本 之 后 ， 调 用 跟踪 会 切换 
到 男 一 个 版 本 ， 以 便 复制 粘贴 。 如 果 想 把 异常 的 调用 跟踪 分 享 给 他 人 (例如 Django IRC 或 Django 用 
户 邮 件 列表 中 友善 的 人 ) ， 寻求 技术 支持 ， 可 以 使 用 这 个 版 本 。 

。 切换 之 后 ， 底 部 会 显示 一 个 “Share this traceback on a public Web site” 按 钮 ， 内 需 尽 击 一 下 下 就 能 把 调用 跟 
踪 发 布 到 网 上 。 点 击 那个 按钮 之 后 ， 调 用 跟踪 会 发 布 到 dpaste 网 站 中 ， 而 且 会 得 到 一 个 URL， 便 于 分 
享 给 其 他 人 。 
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。 接 下 来 是 “Request information” (请 求 信息 ) 部 分 ， 里 丁 
息 : GET 和 POST 信息 、cookie 值 ， 以 及 元 信息 ， 如 CGI 首部。 附录 F 有 一 份 关于 请 求 对 象 中 所 含 信 息 








的 完整 参考 。 














ij 包含 大 量 与 导致 错误 的 人 站 Web 请 求 有 关 的 信 




















。“Request information” 部 分 下 面 是 “Settings”( 设 置 ) 部 分 ， 列 出 Django 当前 的 全 部 设置 。 各 个 设置 在 


附录 D 中 详 述 。 




















在 某 些 情况 下 (如 模板 句法 错误 ) ，Django 的 错误 页 本 























j 还 会 显示 更 多 信息 。 后 文 讨论 Django 的 模板 系统 时 





会 说 明 这 种 情况 。 现 在 ， 把 offset = ;int(offset) 相关 的 那 几 行 代码 的 注释 去 掉 ， 让 视图 函数 能 正确 运行 。 

















如 果 你 喜欢 使 用 print 语句 调试 ， 会 发 现 Django 的 错误 页 本 























特别 有 用 。 














在 视图 的 任意 位 置 临时 插入 assert False 语句 ， 触 发 错误 。 然 后 ， 查 看 局 部 变量 和 程序 的 状态 。 下 面 以 











hours_ahead 视图 为 例 : 








def hours_ahead(request, offset): 
EnV 
offset = int(offset) 
except ValueError: 
raise Http404() 


dt = datetime.datetime.now() + datetime.timedelta(hours=offset) 


assert False 

html = "In %s hour(s), it will be %s. 
" % (offset, dt) 

return HttpResponse(html) 


最 后 要 说 一 点 。 显 然 ， 这 些 信息 大 都 是 敏感 的 ， 暴 漏 了 内 部 的 Python 代码 和 Django 配置 ， 因 此 别 天 真 地 以 
为 可 以 在 网 上 公开 显示 。 不 怀 好 意 的 人 可 以 利用 这 些 信息 做 逆向 工程 ， 然 后 在 你 的 Web 应 用 中 做 些 坏事 。 鉴 














于 此 ， 仅 当 Django 项 目 处 于 调试 模式 时 才 会 显示 错误 页 面 。 第 13 章 会 说 明 如 何 解除 调试 模式 。 现 在 ， 你 只 
( 听 着 耳 熟 ? 本 章 前 面 所 述 的 "Page not found” 错 误 页 面 


需 知道 ，Django 项 目 一 开始 都 自动 处 于 调试 模式 中 。 
也 是 如 此 。) 





2.6 接 下 来 





























念 。 但 在 实际 开发 中 ， 这 是 十 分 糟糕 的 做 法 。Django 











目前 ， 我 们 编写 的 视图 函数 都 直接 在 Python 代码 中 硬 编 码 HTML。 我 这 么 做 是 为 了 简化 ， 以 便 讨论 核心 概 








自 和 天 





底层 代码 隔 开 。 下 一 章 将 讨论 Django 的 模板 引擎 。 


和 了 





























套 简单 却 强 大 的 模板 引 警 ， 能 把 页 画 














的 设计 和 
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你 可 能 注意 到 了 ， 前 一 章 在 示例 视 
示 : 





def current_datetime(request 
now = datetime.datetime. 
html = "It is now %s." % 
return HttpResponse(html 


第 3 章 Django 模板 

















图 中 返回 文本 的 方式 有 些 特别 ， 即 在 Python 代码 中 硬 编码 HTML， 如 下 所 








J 
now() 


now 


) 


这 样 做 虽然 便于 说 明 视图 的 工作 方式 ， 但 是 直接 在 视图 中 硬 编码 HTML 不 是 个 好 主意 。 原 因 如 下 : 


。 只 要 想 修改 页 面 的 设计 就 要 修改 Python 代码 。 网 站 的 设计 肯定 比 底层 的 Python 代码 变化 频繁 ， 因 此 
如 果 无 需 修改 Python 代码 就 能 改变 设计 ， 那 多 方便 。 


。 这 只 是 十 分 简单 的 示例 。 网 页 模板 往往 包含 几 百 行 HTML 和 脚本 。 在 这 样 的 混乱 中 排 错 和 诊断 程序 代 





码 简直 是 蛋 梦 。 (我 说 的 是 














PHP 吗 ? ) 


。 编写 Python 代码 和 设计 HTML 是 两 件 不 同 的 事 ， 多 数 专业 的 Web 设计 团队 会 把 这 两 件 事 交 给 不 同 的 
人 做 (甚至 不 同 的 部 门 ) 。 设 计 师 和 HTML/CSS 程序 员 完 成 工作 不 应 该 需要 编辑 Python 代码 。 

。 如 果 编 写 Python 代码 的 程序 员 和 设计 模板 的 设计 师 能 同时 工作 ， 而 不 用 等 到 一 个 人 编辑 好 包含 Python 
和 HTML 的 文件 之 后 再 交 给 下 一 个 人 ， 工 作 效 率 能 得 到 提升 。 






































鉴于 此 ， 把 页 面 的 设计 与 Python 代码 分 开 ， 结果 更 简洁 ， 也 更 易于 维护 。 为 此 ， 我 们 可 以 使 用 Django 的 模 


板 系 统 。 本 章 就 讨论 这 个 话题 。 


3.1 模板 系统 基础 


Django 模板 是 一 些 文本 字符 串 ， 作 
常 ， 模 板 用 于 生成 HTML， 不 过 Django 模板 可 以 生成 任何 基于 文本 的 格 


板 标签 ) ， 规 定 如 何 显示 文档 。 通 常 


式 。 


Django 模板 背后 的 哲学 























j 是 把 文档 的 表现 与 数据 区 分 开 。 模 板 定义 一 些 占 位 符 和 基本 的 逻辑 ( 模 





























如 果 你 有 编程 背景 ， 或 者 用 过 把 程序 代码 直接 混入 HTML 的 语言 ， 要 记 住 一 件 事 : Django 的 
模板 可 不 是 把 Python 代码 误 入 HIML 这 么 简单 。 模 板 系统 的 设计 目的 是 呈现 表现 ， 而 不 是 程 


序 逻 辑 。 


下 面 看 个 简单 的 模板 示例 。 这 个 Dj 
把 它 理 解 为 一 个 通 函 。 


<html> 
<head> 
<title>Ordering notice</ 
</head> 
<body> 


ango 模板 描述 一 个 HTML 页 面 ， 感 谢 用 户 在 公司 的 网 站 中 购物 。 你 可 以 





title> 
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<h1>0rdering notice</h1> 


<p>Dear {{ person_name }},</p> 


<p>Thanks for placing an order from {{ company }}. It's scheduled to ship on {{ 


ship_date|date:"F j, Y" }}.</p> 


<p>Here are the items you've ordered:</p> 
<ul> 

{% for item in item list %} 

<li>{{ item }}</li>{% endfor %} 
</ul> 


{% if ordered warranty %} 
<p>Your warranty information will be included in the packaging.</p> 
{% else %} 
<p> 
You didn't order a warranty, so you're on your own when 
the products inevitably stop working. 
</p> 
{% endif %} 


<p>Sincerely,<br />{{ company }}</p> 


</body> 
</html> 


这 个 模板 的 大 部 分 内 容 是 HTML， 内 含 一 些 变 量 和 模板 标签 。 下 面 详细 说 明 。 

















两 对 花 括号 包围 的 文本 (如 {{ person_name }}) 是 变量 ,意思 是 “把 指定 变量 的 值 插入 这 里 ”"。 如 何 指 
定 变量 的 值 呢 ? 稍 后 说 明 。 

一 对 花 括号 和 百 分 号 包围 的 文本 (如 {% if ordered_warranty }) 是 模板 标签 。 
标签 的 定义 相当 宽泛 : 只 要 能 让 模板 系统 “做 些 事 ”的 就 是 标签 。 

这 个 示例 模板 中 有 一 个 for 标签 ({% for item in item_list %}) 和 一 个 if 标签 ({% if or- 
dered_warranty %}) 。for 标签 的 作用 与 Python 中 的 for 语句 很 像 ， 用 于 迭代 序列 中 的 各 个 元 素 。 与 
你 预期 的 一 样 ，if 标签 的 作用 是 编写 逻辑 判断 语句 。 


这 里 ，if 标签 检查 ordered_warranty 变量 的 求 值 结果 是 不 是 True。 如 果 是 ， 模 板 系 统 将 显示 {% if 
ordered_warranty %} 和 {% else 9 之 间 的 内 容 ， 如 果 不 是 ， 模 板 系统 将 显示 {% else % 和 {% endif 
%} 之 间 的 内 容 。 注 意 ，{% else 六 是 可 选 的 。 

最 后 ， 这 个 模板 的 第 二 段 包 含 一 个 过 滤器 ， 这 是 调整 变量 格式 最 为 便利 的 方式 。 对 这 个 示例 中 的 {{ 
ship_dateldate:"F j,Y"】} 来 说 ， 我 们 把 ship_date 变量 传 给 date 过 滤器 ， 并 且 为 date 过 滤器 指定 
"F j，Y" 参数 。date 过 滤器 使 用 参数 指定 的 格式 格式 化 日 期 。 过 滤器 使 用 管道 符号 (|) 依附 ， 类 似 


于 Unix 管道 。 
















































































Django 模板 能 访问 多 个 内 置 的 标签 和 过 滤器 ， 接 下 来 的 几 节 会 讨论 其 中 几 个 。 附 录 己 列 出 了 全 部 标签 和 过 滤 
器 ， 你 最 好 熟悉 一 下 ， 知 道 有 哪些 可 用 。 我 们 自己 也 可 以 创建 过 滤器 和 标签 ， 参 阅 第 8 章 。 












































3.2 使 用 模板 系统 


Django 系统 经 过 配置 后 可 以 使 用 一 个 或 多 个 模板 引擎 (如 果 不 用 模板 ， 那 就 不 用 配置 ) 。Django 自 带 了 一 个 
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内 置 的 后 端 ， 用 于 支持 自身 的 模板 引擎 ， 即 Django Template Language (DTL) 。Django 1.8 还 支持 另 一 个 流 
行 的 模板 引 警 ，Jinja2。 如 果 没 有 特别 的 理由 更 换 后 端 ， 应 该 使 用 DTL 一 一 如 果 编 写 的 是 可 插入 式 应 用 ， 而 

且 带 有 模板 ， 更 应 该 如 此 。Dijango 包含 模板 的 contrib 应 用 ， 如 django.contrib.admtn， 使 用 的 就 是 DTL。 

本 章 的 所 有 示例 都 将 使 用 DTL。 高 级 的 模板 话题 ， 如 配置 第 三 方 模板 引擎 ， 参 阅 第 8 章 。 在 视图 中 使 用 
Django 模板 之 前 ， 先 稍微 说 明 一 下 DIL， 了 解 它 的 工作 方式 。 若 想 在 Python 代码 中 使 用 Django 的 模板 系 
统 ， 基 本 方式 如 下 : 









































1. 以 字符 串 形式 提供 原始 的 模板 代码 ， 创 建 Template 对 象 。 


2.， 在 Template 对 象 上 调用 render() 方法 ， 传 人 一 系列 变量 (上 下 文 ) 。 返 回 的 是 完全 演 染 模板 后 得 到 
的 字符 串 ， 模 板 中 的 变量 和 模板 标签 已 经 根据 上 下 文 求 出 值 了 。 























用 代码 来 说 ， 上 述 过 程 如 下 : 


>>> from django import template 

>>> 七 = template.Template('My name is {{ name }}.') 
>>> C = template.Context({'name': 'Nige'}) 

>>> print (t.render(c)) 

My name is Nige. 

>>> C = template.Context({'name': 'Barry'}) 

>>> print (t.render(c)) 

My name is Barry. 


接 下 来 的 几 节 详 述 各 步 。 





3.2.1 创建 Template 对 象 





创建 Template 对 象 最 简单 的 方式 是 直接 实例 化 。Template 类 在 django.template 模块 中 ， 构 造 方法 接受 一 个 
参数 ， 即 原始 的 模板 代码 。 下 面 在 Python 交互 式 解释 器 中 通过 代码 说 明 。 在 第 1 章 创 建 的 mysite 项 目 目录 
中 输入 python manage.py sheLL， 启 动 交 互 式 解释 器 。 

















下 面 说 明 模 板 系统 的 一 些 基本 知识 : 


>>> from django.tempLate import TempLate 
>>> 七 = Template('My name is {{ name }}.') 
>>> print (t) 





在 交互 式 解释 器 中 输入 上 述 代码 后 会 得 到 类 似 下 面 的 输出 : 














<django.tempLate.base.TempLate object at 0x030396B0> 


在 每 次 得 到 的 输出 中 ，6x6360396B9 那 部 分 是 不 同 的 ， 而 且 也 无 关 紧 要 。 那 是 Python 的 细节 (如 果 一 定 想 知道 
的 话 ， 我 告诉 你 ， 那 是 Template 对 象 的 “标识 ”) 。 


























创建 Template 对 象 时 ， 模 板 系统 会 把 原始 的 模板 代码 编译 成 内 部 使 用 的 优化 形式 ， 为 泻 染 做 好 准备 。 但 是 ， 
如 果 模 板 代 码 中 有 句法 错误 ， 调 用 TempLate() 会 导致 TemplateSyntaxError 异常 抛 出 : 

















>>> from django.tempLate import TempLate 
>>> 七 = Template('{% notatag %}') 
Traceback (most recent call Last) : 

File "", line 1，in ? 


django. template.base.TemplateSyntaxError: Invalid block tag: 'notatag' 
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这 里 的 “block tag”( 块 级 标签 ) 指 的 是 {% notatag %}。“ 块 级 标签 "和 “模板 标签 "是 同一 个 事物 。 遇 到 下 述 各 
种 情况 时 ， 模 板 系统 都 会 抛 出 TemplateSyntaxError: 





。 无 效 标签 

。 有 效 标签 的 无 效 参 数 

。 无 效 过 滤器 

。 有 效 过 滤器 的 无 效 参 数 

。 无 效 模板 句法 

。 未 关闭 的 标签 (对 需要 结束 标签 的 模板 标签 而 言 ) 











3.2.2 演 染 模板 


有 了 Template 对 象 之 后 ， 可 以 为 其 提供 上 下 文 ， 把 数据 传 给 它 。 上 下 文 就 是 一 系列 模板 变量 和 相应 的 值 。 模 
板 使 用 上 下 文 填 充 变量 ， 求 值 标签 。 在 Django 中 ， 上 下 文 使 用 django.template 模块 中 的 Context 类 表示 。 

它 的 构造 方法 接受 一 个 可 选 参数 ， 一 个 字典 ， 把 变量 名 映射 到 值 上 。 “填充 ”模板 的 方式 是 ， 在 Template 对 象 
上 调用 render() 方法 ， 并 传人 上 下 文 : 















































>>> from django.tempLate import Context，TempLate 
>>> 七 = Template('My name is {{ name }}.') 

>>> C = Context({'name': 'Stephane'}) 

>>> t.render(c) 

'My name is Stephane.' 





旁 注 3-1， 一 个 特殊 的 Python 提示 符 























如 果 你 用 过 Python， 可 能 会 想 ， 为 什么 运行 python manage.py sheLL， 而 不 是 python (或 python3) 。 这 
两 个 命令 都 能 启动 交互 式 解释 器 ， 但 是 manage.py shell 命令 有 个 关键 区 别 : 在 启动 解释 器 之 前 ， 告 诉 
Django 使 用 哪个 设置 文件 。Django 的 很 多 部 分 ， 包 括 模板 系统 ， 依 赖 于 设置 ， 如 果 不 告 诉 Django 使 用 
哪个 设置 ， 你 就 无 法 使 用 它们 。 如 果 你 好 奇 ， 我 来 说 说 这 背后 的 原理 。Dijango 查找 一 个 名 为 DJAN- 
G0_SETTINGS_MODULE 的 环境 变量 ， 其 值 是 导入 settings.py 的 路 径 。 例 如 ，DJANGO_SETTINGS_MODULE 的 值 
可 能 是 'mysite.settings' (假设 mysite 在 Python 路 径 中 ) 。 执 行 python manage.py shell 命令 时 ， 它 
会 为 你 设 定 DJIANG0_SETTINGS_MODULE。 在 这 些 示例 中 必须 使 用 python manage.py shell， 否则 Django 会 
抛 出 异常 。 



















































































3.3 字典 和 上 下 文 























Python 字典 是 键 和 值 的 映射 。Context 对 象 类 似 于 字典 ， 但 是 它 有 额外 的 功能 ， 参 阅 第 8 章 。 


变量 名 必须 以 字母 开头 (A-Z 或 a-z) ， 随 后 可 以 跟着 任意 多 个 字母 、 数 字 、 下 划 线 和 点 号 。 (点 号 是 特殊 
的 ， 稍 后 说 明 。) 变量 名 区 分 大 小 写 。 下 面 是 编译 和 演 染 模板 的 示例 ， 使 用 的 模板 类 似 于 本 章 开 头 那个 : 















































>>> from django.tempLate import Template, Context 


>>> raw_template = <p>Dear {{ person_name }},</p> 
. <p> 
Thanks for placing an order from {{ company }}. It's scheduled to 
. Ship on {{ 
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ship_date|date:"F j, Y" 
}}. 
</p> 


. {% if ordered_warranty %} 
. <p>Your warranty information will be included in the packaging.</p> 
. {% else %} 
. <p> 
You didn't order a warranty, so you're on your own when 
. the products inevitably stop working. 
</p> 
... {% endif %} 
. <p>Sincerely,<br />{{ company }}</p>""" 
>>> t = Template(raw_template) 
>>> import datetime 
>>> C = Context({'person_name': 'John Smith ' ， 
'company': 'Outdoor Equipment ' ， 
'ship_date': datetime.date(2015，7，2)， 
"ordered_warranty' : False}) 
>>> t.render(c) 
"<p>Dear John Smith,</p>\n\n<p>Thanks for placing an order from Outdoor Equipment. It\ 
's scheduled to\nship on July 2,2015.</p>\n\n\n<p>You didn't order a warranty, so you\ 
"re on your own when\nthe products inevitably stop working.</p>\n\n\n<p>Sincerely,<br\ 
/>0utdoor Equipment</p>"” 





。 首先 ， 导 入 Template 和 Context 类 ， 二 者 都 在 django.template 模块 中 。 

。 把 模板 的 原始 文本 保存 在 raw_template 变量 中 。 注 意 ， 我 们 使 用 三 个 引号 标明 那个 字符 串 ， 这 是 因为 
它 分 为 多 行 。 使 用 单 引 号 标明 的 字符 串 不 能 分 成 多 行 。 

。 接 下 来 ， 把 raw_template 传 给 Template 类 的 构造 方法 ， 创 建 一 个 模板 对 象 ， 名 为 t。 

。 从 Python 的 标准 库 中 导入 datetime 模块 ， 因 为 下 一 个 语句 要 使 用 。 


。 然后 ， 创 建 一 个 Context 对 象 ， 名 为 c。Context 构造 方法 接受 一 个 Python 字典 ， 把 变量 名 映射 到 值 
上 。 这 里 ， 我 们 把 person_name 设 为 'John Smith'， 把 company 设 为 '0utdoor Equipment' ， 等 等 。 


。 最 后 ， 在 模板 对 象 上 调用 render() 方法 ， 并 且 传人 上 下 文 。 返 回 的 是 泻 染 后 的 模板 ， 即 把 模板 变量 替 
换 成 变量 的 值 ， 并 且 执行 模板 标签 。 注 意 ， 显 示 的 是 "You didn't order a warranty”， 因 为 ordered_war- 
ranty 变量 的 求 值 结果 是 Fatse。 还 要 注意 日 期 ， 根 据 格 式 字符 串 F j，Y， 显 示 为 July 2，2915。 ( 稍 
后 说 明 date 过 滤 需 的 格式 字符 串 。) 
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如 果 你 刚 接触 Python， 可 能 会 想 ， 输 出 中 为 什么 包含 换行 符 〈\n) ， 而 不 直接 换行 。 之 所 以 这 样 ， 是 因为 
Python 交互 式 解释 器 的 一 个 微妙 之 处 : t.render(c) 返回 一 个 字符 串 ， 而 交互 式 解 释 器 默认 显示 字符 串 的 表 
示 形 式 ， 而 不 是 打印 字符 串 的 值 。 如 果 想 让 换行 显示 为 真正 的 换行 ， 而 不 是 \n 字符 ， 使 用 print 函数 : 





print (t.render(c))。 





























以 上 就 是 Django 模板 系统 的 基本 用 法 : 编写 模板 字符 串 ， 创 建 Template 对 象 ， 创 建 Context 对 象 ， 然 后 调 


用 render() 方法 。 
































3.3.1 多 个 上 下 文 ， 同 一 个 模板 








得 到 Template 对 象 之 后 ， 可 以 用 其 演 染 多 个 上 下 文 。 例 如 : 
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>>> from django.tempLate import Template, Context 
>>> 七 = Template('Hello, {{ name }}') 

>>> print (t.render(Context({'name': 'John'}))) 
Hello, John 

>>> print (t.render(Context({'name': 'Julie'}))) 
Hello, Julie 

>>> print (t.render(Context({'name': 'Pat'}))) 
Hello, Pat 























像 这 样 使 用 同一 个 模板 泻 染 多 个 上 下 文 ， 比 分 成 多 次 创建 Template 对 象 再 调用 render() 效率 高 : 


# 不 好 

for name in ('John', 'Julie', 'Pat'): 

t = Template('Hello, {{ name }}') 

print (t.render(Context({'name': name}))) 


# 好 

t = Template('Hello, {{ name }}') 

for name in ('John', 'Julie', 'Pat'): 
print (t.render(Context({'name': name}))) 





Django 解析 模板 的 速度 相当 快 。 在 背后 ， 解 析 的 大 部 分 工作 通过 调用 一 个 正则 表达 式 完成 。 这 与 基于 XML 
的 模板 系统 有 显著 区 别 ，XML 解析 器 会 带 来 额外 的 消耗 ， 从 而 导致 演 染 速度 比 Django 的 模板 泻 染 引 苟 慢 几 
个 数量 级 。 














3.3.2 上 下 文 变量 查找 





目前 所 举 的 示例 ， 传 入 上 下 文 的 都 是 简单 的 值 ， 大 多 数 是 字符 串 ， 此 外 还 有 一 个 示例 用 到 了 datetime.date 
对 象 。 然 而 ， 模 板 系统 能 优雅 处 理 很 多 复杂 的 数据 结构 ， 例 如 列表 、 字 典 和 自 定义 的 对 象 。 遍 历 Django 模板 
中 复杂 数据 结构 的 关键 是 点 号 (.) 。 


点 号 可 以 访问 字典 的 键 、 属 性 、 方 法 或 对 象 的 索引 。 最 好 通过 几 个 示例 说 明 。 假 如 我 们 把 一 个 Python 字典 传 
给 模板 。 若 想 通过 键 访问 那个 字典 中 的 值 ， 要 使 用 点 号 : 































































































>>> from django.tempLate import Template, Context 
>>> person = {'name': 'Sally', 'age': '43'} 

>>> 七 = Template('{{ person.name }} is {{ 
person.age 

}} years old.') 

>>> C = Context({'person': person}) 

>>> t.render(c) 

'Sally is 43 years old.' 








类 似 地 ， 通 过 点 号 还 可 以 访问 对 和 象 的 属性 。 例 如 ，Python 的 datetime.date 对 象 有 year、month 和 day 属性 ， 
在 Django 模板 中 可 以 使 用 点 号 访问 这 些 属性 : 




















>>> from django.template import Template, Context 
>>> import datetime 

>>> d = datetime.date(1993, 5, 2) 

>>> d.year 

1993 

>>> d.month 

9 
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>>> d.day 


>>> 七 = Template('The month is {{ date.month }} 
and the year is {{ date.year }}.') 

>>> C = Context({ ' date': d}) 

>>> t.render(c) 

"The month is 5 and the year is 1993.' 


下 述 示例 自 定义 一 个 类 ， 以 此 说 明 也 可 以 通过 点 号 访问 任意 对 象 的 属性 : 





>>> from django.tempLate import Template, Context 
>>> CLass Person(object) : 
def _init (self, first name, last_name): 
ee self.first name, self.last name = 
first name, last_name 
>>> 七 = Template('Hello, {{ person.first _ name }} {{ person.Last_name }}.') 
>>> C = Context({'person': Person('John', 'Smith')}) 
>>> t.render(c) 
'Hello, John Smith.' 


刁 | 


还 可 以 通过 点 号 引用 对 象 的 方法 。 例 如 ， 每 个 Python 字符 串 都 有 upper() 和 isdigit() 方法， 在 Django 模板 
中 可 以 使 用 点 号 句法 调用 它们 : 





刁 | 


>>> from django.template import Template, Context 

>>> 七 = Template('{{ var }} -- {{ var.upper }} -- {{ var.isdigit }}') 
>>> t.render(Context({'var': 'hello'})) 

'hello -- HELLO -- False' 

>>> t.render(Context({'var': '123'})) 

'123 -- 123 -- True' 


注意 ， 方 法 调用 中 没有 括号 。 此 外 ， 不 能 给 方法 传递 变量 ， 只 能 调用 无 需 参数 的 方法 。 (本 章 后 面 将 说 明 这 
里 的 哲学 。) 最 后 ， 还 可 以 使 用 点 号 访问 列表 索引 ， 例 如 : 


>>> from django.template import Template, Context 
>>> 七 = Template('Item 2 is {{ items.2 }}.') 

>>> C = Context({'items': ['apples', 'bananas', 
'carrots']}) 

>>> t.render(c) 

'Item 2 is Carrots.' 





不 允许 使 用 负数 索引 。 例 如 ， 模 板 变 量 {{ items.-1 }} 会 导致 TemplateSyntaxError 抛 出 。 


提醒 一 下 ，Python 列表 的 索引 从 零 开始 。 第 一 个 元 素 的 索引 是 0， 第 二 个 元 素 的 索引 是 1， 以 
此 类 推 。 


总 结 起 来 ， 模 板 系 统 遇 到 变量 名 中 的 点 号 时 会 按照 下 述 顺 序 尝试 查找 : 


。 字典 查找 (如 foo["bar"]) 
性 查找 (如 foo.bar) 
。 方法 调用 (如 foo.bar()) 








了 TH 
好 
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。 列表 索引 查找 (如 foo[2] ) 

















模板 系统 将 使 用 第 一 个 可 用 的 类 型 ， 这 是 一 种 短路 逻辑 。 点 号 查找 可 以 艇 套 多 层 。 例 如 ， 下 述 示例 使 用 的 {{ 
person.name.upper }}， 相 当 于 一 个 字典 查找 (person['name']) 加 上 一 个 方法 调用 (upper()) : 






































>>> from django.template import Template, Context 
>>> person = {'name': 'Sally', 'age': '43'} 

>>> 七 = Template('{{ person.name.upper }} is {{ 
person.age 

}} years old.') 

>>> C = Context({'person': person}) 

>>> t.render(c) 

'SALLY is 43 years old.' 


3.3.3 方法 调用 的 行为 
方法 调用 与 其 他 几 种 查找 稍微 复杂 一 些 。 下 面 是 要 知道 的 几 件 事 : 




















。 在 方法 查找 的 过 程 中 ， 如 果 方 法 抛 出 异常 ， 异 常会 向 上 冒 泡 ， 除 非 异常 有 silent_variable_failure 属 
性 ， 而 且 值 为 True。 如 果 异 常 确 实 有 silent_variable_failure 属性 ， 使 用 引擎 的 string_if_invalid 


















































配置 选项 (默认 为 一 个 空 字符 串 ) 演 染 变量 。 例 如 : 





>>> 七 = Template("My name is {{ person.first_name }}.") 
>>> class PersonCLass3: 
def first_name(self): 
raise AssertionError("foo") 
>>> p = PersonClass3() 
>>> t.render(Context({"person": p})) 
Traceback (most recent call last): 


AssertionError: foo 


>>> class SilentAssertionError(Exception): 
silent_variable_ failure = True 
>>> class PersonCLass4: 
def first_name(self): 
raise SilentAssertionError 
>>> p = PersonClass4() 
>>> t.render(Context({"person": p})) 


"My name is . 











。 方法 不 能 有 必须 的 参数 。 和 否则， 模板 系统 向 后 移动 到 下 一 种 查询 类 型 (列表 索引 查询 ) 。 


。 按照 设计 ，Django 限制 了 在 模板 中 可 以 处 理 的 逻辑 量 ， 因 此 在 模板 中 不 外 








在 视图 中 计算 之 后 再 传 给 模板 显示 。 


。 显然 ， 有 些 方法 有 副作用 ， 如 果 人 允许 模板 系统 访问 这 样 的 方法 ， 那 就 
漏洞 。 




















E 给 方法 传递 参数 。 数 据 应 该 








于 











碟 之 极 ， 其 至 还 可 能 埋 下 安全 











。 假如 有 个 BankAccount 对 象 ， 它 有 个 delete() 方法 。 如 果 模 板 中 有 {{ account.delete }} 这 样 的 内 
容 ， 其 中 account 是 BankAccount 对 象 ， 那 么 泻 染 模板 时 会 把 account 删除 。 为 了 避免 这 种 行为 ， 在 方 








法 上 设 定 函 数 属性 alters_data: 


def deLete(seLf) : 
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# 删除 账户 
delete.alters_data = True 








模板 系统 不 会 执行 方法 。 继 续 使 用 前 面 的 例子 。 如 果 模 板 中 有 {{ account.deLete 
， 而 delete() 方法 设 定 了 alters_data=True， 那 么 演 染 模板 时 不 会 执行 delete() 方法 ， 引 擎 会 使 用 
Se 的 值 蔡 换 那 个 变量 。 


: 为 Django 模型 对 象 动态 生成 的 delete() 和 save( ) 方法 自动 设 定 了 alters_data = True。 





























由 




















3.3.4 如 何 处 理 无 效 变量 

















一 般 来 说 ， 如 果 变 量 不 存在 ， 模 板 系统 在 变量 处 插入 引擎 的 string_if_invalid 配置 选项 。 这 个 选项 的 默认 
值 为 一 个 空 字符 串 。 例 如 : 











>>> from django.template import Template, Context 
>>> 七 = Template('Your name is {{ name }}.') 

>>> t.render(Context()) 

"Your name is .， 

>>> t.render(Context({'var': 'hello'})) 
'Your name is .， 

>>> t.render(Context({'NAME': 'hello'})) 
'Your name is .， 

>>> t.render(Context({'Name': 'hello'})) 


'Your name is . 





这 一 行为 比 抛 出 异常 好 ， 因 为 遇 到 人 为 错误 时 能 迅速 恢复 。 在 上 述 示例 中 ， 所 有 查找 都 失败 ， 因 为 变量 名 的 
大 小 写 不 对 ， 或 者 名 称 错误 。 在 现实 中 ， 如 果 因 为 模板 中 有 小 小 的 句法 错误 就 导致 网 站 不 可 访问 ， 着 实 无 法 
让 人 接受 。 


























3.4 基本 的 模板 标签 和 过 滤器 


前 面 说 过 ，Django 的 模板 系统 自 带 了 一 些 内 置 的 标签 和 过 滤器 。 下 面 几 节 说 明 其 中 最 常用 的 几 个 。 








3.4.1 标签 


if/else 








{% if %} 计算 变量 的 值 ， 如 果 为 真 〈 即 存在 、 不 为 空 ， 不 是 假 值 ) ， 模 板 系统 显示 {% if %} 和 {% endif %} 
之 间 的 内 容 。 例 如 : 

















{% if today_is weekend %} 
<p>Welcome to the weekend!</p> 
{% endif %} 


{% else %} 标签 是 可 选 的 : 


{% if today_is weekend %} 
<p>Welcome to the weekend!</p> 
{% else %} 

<p>Get back to work.</p> 

{% endif %} 





if 标签 还 可 以 有 一 个 或 多 个 {% elif 9 子 句 ， 
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{% if athLete_List %} 

Number of athLetes: {{ athlete list|length }} 

{% elif athlete in locker_room list %} 

<p>Athletes should be out of the locker room soon! </p> 
{% elif ... 


{% else %} 
<p>No athletes. </p> 
{% endif %} 


{% if %} 支持 使 用 and、or 或 not 测试 多 个 变量 ,或 者 取 反 指定 的 变量 。 例 如 : 


{% if athlete list and coach list %} 
<p>Both athletes and coaches are available. </p> 
{% endif %} 


{% if not athlete list %} 
<p>There are no athletes. </p> 
{% endif %} 


{% if athlete list or coach list %} 
<p>There are some athletes or some coaches. </p> 
{% endif %} 


{% if not athlete list or coach list %} 
<p>There are no athletes or there are some coaches. </p> 
{% endif %} 


{% if athlete_list and not coach_ list %} 
<p>There are some athletes and absolutely no coaches. </p> 
{% endif %} 





在 同一 个 标签 中 可 以 同时 使 用 and 和 or， 此 时 ，and 的 优先 级 比 or 高。 例如: 
{% if athlete list and coach list or cheerleader list %} 


像 下面 这 样 解释 : 





if (athlete list and coach list) or cheerleader list 


在 if 标签 中 使 用 括号 是 无 效 的 句法 。 


如 果 需 要 通过 括号 指明 优先 级 ， 应 该 使 用 向 套 的 if 标签 。 不 支持 使 用 括号 控制 操作 的 顺序 。 如 果 觉 得 有 必要 
使 用 括号 ， 可 以 考虑 在 模板 外 部 执行 逻辑 ， 然 后 通过 专用 的 模板 变量 传人 结果 。 或 者 ， 直 接 使 用 骨 套 的 {% 
if %} 标签 ， 如 下 所 示 : 








{% if athlete list %} 
{% if coach list or cheerleader list %} 
<p>We have athletes, and either coaches or cheerleaders! </p> 
{% endif %} 
{% endif %} 
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多 次 使 用 相同 的 逻辑 运算 符 没 问题 ， 但 是 不 能 混用 不 同 的 运算 符 。 例 如 ， 下 述 写法 是 有 效 的 : 











{% if athlete list or coach list or parent_ list or teacher_list %} 


每 个 {% if 都 必须 有 配对 的 人 % endif 和。 否则 ，Django 会 抛 出 TempLateSyntaxError 异常 。 





for 





{% for %} 标签 用 于 迭代 序列 中 的 各 个 元 素 。 与 Python 的 for 语句 一 样 ， 句 法 是 for X in Y， 其 中 Y 是 要 迭 
代 的 序列 ，X 是 单 次 循环 中 使 用 的 变量 。 每 次 迭代 时 ， 模 板 系 统 会 泻 染 { for 时 和 {% endfor 失 之 间 的 内 
容 。 例 如 ， 可 以 使 用 下 述 模板 显示 athlete_list 变量 中 的 运动 员 : 











<UL> 
{% for athlete in athlete_ list %} 
<li>{{ athlete.name }}</li> 
{% endfor %} 

</ul> 


在 标签 中 添加 reversed， 反 向 迭代 列表 : 


{% for athlete in athlete_ list reversed %} 
{% endfor %} 


{% for %} 标签 可 以 般 套 : 


{% for athlete in athlete_ list %} 

<h1>{{ athlete.name }}</h1> 

<ul> 
{% for sport in athlete.sports_played %} 
<li>{{ sport }}</li> 
{% endfor %} 

</ul> 

{% endfor %} 


如 果 需 要 迭代 由 列表 构成 的 列表 ， 可 以 把 每 个 子 列表 中 的 值 拆 包 到 独立 的 变量 中 。 
比如 说 上 下 文中 有 一 个 包含 (x;y) 坐标 点 的 列表 ， 名 为 potnts， 可 以 使 用 下 述 模板 输出 这 些 坐标 点 : 














{% for x，y in points %} 
<p>There is a point at {{ x }},{{ y }}</p> 
{% endfor %} 




















如 果 需 要 访问 字典 中 的 元 素 ， 也 可 以 使 用 这 个 标签 。 如 果 上 下 文中 包含 一 个 字典 data， 可 以 使 用 下 述 模板 显 
示 字 典 的 键 和 值 : 


























{% for key, value in data.items %} 


{{ key }}: {{ value }} 
{% endfor %} 


通常 ， 和 迭代 列表 之 前 要 先 检查 列表 的 大 小 ， 如 果 为 空 ， 显 示 一 些 特殊 的 文字 : 





{% if athLete_List %} 


{% for athlete in athLete_List %} 
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<p>{{ athLete.name }}</p> 
{% endfor %} 


{% else %} 
<p>There are no athletes. Only computer programmers.</p> 
{% endif %} 











这 种 做 法 太 常 见 了 ， 因 此 for 标签 支持 一 个 可 选 的 {% empty 只 子 句 ， 用 于 定义 列表 为 空 时 显示 的 内 容 。 下 
述 示例 与 前 一 个 等 效 : 


{% for athlete in athlete list %} 

<p>{{ athlete.name }}</p> 

{% empty %} 

<p>There are no athletes. Only computer programmers.</p> 
{% endfor %} 








在 循环 结束 之 前 ， 无 法 “跳出 "。 如 果 需 要 这 么 做 ， 修 改 要 和 迭代 的 变量 ， 只 包含 需要 迭代 的 值 。 
同样 ， 也 没有 “continue” 语 句 ， 不 能 立即 返回 到 循环 的 开头 。 (这 种 设计 方式 背后 的 原因 参见 3.5 万。) 


在 { for % 循环 内 部 ， 可 以 访问 一 个 名 为 fortoop 的 模板 变量 。 这 个 变量 有 几 个 属性 ， 它们 可 以 获知 
循环 进程 的 一 些 信息 : 











。 forloop.counter 的 值 是 一 个 整数 ， 表 示 循 环 的 次 数 。 这 个 属性 的 值 从 1 开始 ， 因 此 第 一 次 循环 时 ， 
forloop.counter 等 于 1。 下 面 举 个 例子 : 




















{% for item in todo list %} 
<p>{{ forloop.counter }}: {{ item }}</p> 
{% endfor %} 


。 fortLoop.counterg 与 forloop.counter 类 似 ， 不 过 是 从 零 开始 的 。 第 一 次 循环 时 ， 其 值 为 9。 


。 forloop.revcounter 的 值 是 一 个 整数 ， 表 示 循 环 中 剩余 的 元 素数 量 。 第 一 次 循环 时 ，for- 
Loop.revcounter 的 值 是 序列 中 要 遍历 的 元 素 总 数 。 最 后 一 次 循环 时 ，forloop.revcounter 的 值 为 1。 


。 forloop.revcounter0 与 forloop.revcounter 类 似 ， 不 过 索引 是 基于 零 的 。 第 一 次 循环 时 ，for- 
loop.revcounter0 的 值 是 序列 中 元 素数 量 减 去 一 。 最 后 一 次 循环 时 ，forLoop.revcounterg 的 值 为 0。 


。 forloop.first 是 个 布尔 值 ， 第 一 次 循环 时 为 True。 需 要 特殊 处 理 第 一 个 元 素 时 很 方便 : 






































{% for object in objects %} 
{% if forloop.first %} 
<li class="first"> 
{% else %} 
<li> 
{% endif %} 


({ object }} 
</li> 
{% endfor %} 














。 forloop.last 是 个 布尔 值 ， 最 后 一 次 循环 时 为 True。 经 常用 它 在 一 组 链接 之 间 放 置 管道 符号 








{% for Link in links %} 
{{ link }}{% if not forloop.last %} | {% endif %} 
{% endfor %} 
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上 述 模板 代码 的 输出 可 能 是 : 
Link1 | Link2 | Link3 | Link4 
此 外 ， 还 经 常用 它 在 一 组 单词 之 间 放 置 逗 号 : 


<p>Favorite places:</p> 
{% for p in places %} 

{{ p }}{% if not forloop.last %}, {% endif %} 
{% endfor %} 


。 在 瞬 套 的 循环 中 ，forLoop.parentLoop 引用 父 级 循环 的 forLoop 对 象 。 下 面 举 个 例子 : 





{% for country in countries %} 
<table> 
{% for city in country.city list %} 
tr 
<td>Country #{{ forloop.parentloop.counter }}</td> 
<td>City #{{ forloop.counter }}</td> 
<td>{{ city }}</td> 
</tr> 
{% endfor %} 
</table> 
{% endfor %} 


forloop 变量 只 在 循环 内 部 可 用 。 模 板 解 析 器 遇 到 {% endfor %} 时 ，forloop 随 之 消失 。 





上 下 文 和 forloop 变量 


在 {% for %} 块 中 ， 现 有 变量 会 让 位 ， 防 止 覆 盖 forloop 变量 。Django 把 移动 的 上 下 文 放 到 
forloop.parentloop 中 。 通 常 ， 你 无 须 担心 ， 但 是 如 果 有 名 为 forloop 的 模板 变量 (不 建议 这 
人 么 做 ) ， 在 {% for %} 块 中 会 重 命 名 为 forLoop.parentLoop。 





ifequal/ifnotequal 





Django 模板 系统 不 是 功能 全 面 的 编程 语言 ， 因 此 不 允许 执行 任意 的 Python 语句 (3.5 节 详 述 ) 。 
然而 ， 模 板 经 常 需 要 比较 两 个 值 ， 在 相等 时 显示 一 些 内 容 。 为 此 ，Django 提供 了 {% ifequal 9 标签 。 





{% ifequal %} 标签 比较 两 个 值 ， 如 果 相 等 ， 显 示 {% ifequal } 和 {% endifequal %} 之 间 的 内 容 。 下 述 示例 
比较 模板 标签 user 和 currentuser : 


{% ifequal user currentuser %} 
<hi>Welcome!</h1i> 
{% endifequal %} 








参数 可 以 是 硬 编码 的 字符 串 ， 使 用 单 引号 或 双 引 号 都 行 ， 因 此 下 述 代码 是 有 效 的 : 

















{% ifequal section 'sitenews' %} 
<h1>Site News</h1> 
{% endifequal %} 


{% ifequal section "community" %} 
<h1i>Community</h1> 
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{% endifequal %} 


与 {% if %} 一 样 ，{% ifequal %} 标签 支持 可 选 的 {% else 时 子 句 : 





{% ifequal section 'sitenews' %} 
<h1>Site News</h1> 

{% else %} 
<h1>No News Here</h1> 

{% endifequal %} 


{% ifequal %} 的 参数 只 能 是 模板 变量 、 字 符 串 、 整 数 和 小 数 。 下 面 是 有 效 的 示例 : 


{% ifequal variable 1 %} 

{% ifequal variable 1.23 %} 
{% ifequal variable 'foo' %} 
{% ifequal variable "foo" %} 




















其 他 变量 类 型 ， 例 如 Python 字典 、 列 表 或 布尔 值 ， 不 能 在 { ifequal %} 中 硬 编码 。 下 面 是 无 效 的 示例 : 


{% ifequal variable True %} 
{% ifequal variable [1, 2, 3] %} 
{% ifequal variable {'key': 'value'} %} 














如 果 想 测试 真 假 ， 应 该 使 用 {% if 标签 。 


ifequal 标签 可 以 替换 成 if 标签 和 == 运算 符 。 














{% ifnotequal %} 的 作用 与 ifequal 类 似 ， 不 过 它 测试 两 个 参数 是 否 不 相等 。ifnotequal 标签 可 以 替换 成 if 
标签 和 != 运算 符 。 


注释 
与 HTML 和 Python 一 样 ，Django 模板 语言 支持 注释 。 注 释 使 用 {# 好 标明 : 





{# This is a comment #} 
演 染 模板 时 ， 不 输出 注释 。 使 用 这 种 句法 编写 的 注释 不 能 分 成 多 行 。 这 一 限制 有 助 于 提升 模板 解析 性 能 。 
在 下 述 模板 中 ， 泻 染 的 结果 与 模板 完全 一 样 〈 即 注释 标签 不 会 解析 为 注释 ) : 














This is a {# this is not 
a Comment #} 
test. 

















如 果 想 编写 多 行 注释 ， 使 用 {% comment %} 模板 标签 ， 如 下 所 示 : 











{% comment %} 

This is a 
multi-line comment. 
{% endcomment %} 


注释 标签 不 能 舱 套 。 








3.4.2 过 滤器 



































本 章 前 面 说 过 ， 模 板 过 滤器 是 在 显示 变量 之 前 调整 变量 值 的 简单 方式 。 过 滤器 使 用 管道 符号 指定 ， 如 下 所 
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示 : 


{{ name|Lower }} 





上 述 代码 先 通 过 Lower 过 滤器 调整 {{ name }} 变量 的 值 一 一 把 文本 转换 成 小 写 ， 然 后 再 显示 。 过 滤器 可 以 串 





接 ， 即 把 一 个 过 滤器 的 输出 传 给 下 一 个 过 滤器 。 
下 述 示例 获取 列表 中 的 第 一 个 元 素 ， 然 后 将 其 转换 成 大 写 ， 
{{ my_list|first|upper }} 


9 些 过 滤器 可 以 接受 参数 。 过 滤器 的 参数 放 在 冒号 之 后 ， 始 终 放 在 双 引 号 内 。 例 如 : 




















{{ bio|truncatewords:"30" }} 





上 述 示例 显示 bio 变量 的 前 30 个 词 。 








下 面 是 几 个 最 重要 的 过 滤器 。 其 余 的 过 滤器 在 附录 EE 中 说 明 。 














。 addslashes: 在 反 斜 线 、 单 引号 和 双 引 号 前 面 添 加 一 个 反 斜 线 。 可 用 于 转 义 字符 串 。 例 如 : {{ vat- 














ueladdslashes }}。 

。 date: 根据 参数 中 的 格式 字符 串 格 式 化 date 或 datetime 对 象 。 例 如 : {{ pu 
}}。 格 式 字 符 串 在 附录 了 中 说 明 。 

。 Length: 返回 值 的 长 度 。 对 列表 来 说 ， 返 回 元 素 的 数量 。 对 字符 串 来 说 ， 
未 定义 ， 返 回 9。 











3.5 理念 和 局 限 


现在 ， 你 已 经 大 致 了 解 了 Django Template Language (DTL) ， 或 许 该 说 明 一 下 背后 





道 ，DTL 的 局 限 是 故意 为 之 的 。 


b_ date|ldate:"F j, Y" 








返回 字符 的 数量 。 如 果 变 量 


的 设计 理念 了 。 首 先 要 知 





Django 发 端 于 在 线 新 闻 站 点 ， 其 特点 是 大 容量 、 变 化 频繁 。 最 初 设计 Django 的 人 对 DTL 有 非常 明确 的 理念 








预 设 。 


如 今 ， 这 些 理 念 仍然 是 Django 的 核心 。 它 们 是 : 








js 


.表现 与 逻辑 分 离 
避免 重复 

与 HIML 解 耦 

XML 不 好 

不 要 求 具 备 设 计 能 力 
透明 处 理 空格 

不 重 造 一 门 编程 语言 
确保 安全 有 保障 
可 扩展 






























































浊 


下 面 分 述 各 点 。 





1， 表 现 与 逻辑 分 离 
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模板 系统 用 于 控制 表现 及 与 其 相关 的 逻辑 ， 仅 此 而 已 。 超 出 


.避免 重复 

















这 一 基本 目标 的 功能 都 不 应 该 支持 。 


大 多 数 动态 网 站 都 使 用 某 种 全 站 通用 的 设计 ， 例 如 通用 的 页 头 、 页 脚 、 导 航 栏 ， 等 等 。Django 模板 系 





全 
理念 。 

















.与 HTML 解 耦 














统 应 该 为 此 提供 便利 的 方式 ， 把 这 些 元 素 存储 在 一 个 位 置 ， 减 少 重复 的 代码 。 模 板 继 承 背 后 就 是 这 个 


模板 系统 不 应 该 只 能 输出 HTML， 还 要 能 够 生成 其 他 基于 文本 的 格式 (也 就 是 纯 文本 ) 。 


XML 不 
如 果 使 
.不 要 求 


























凡 该 作为 模板 语言 
用 XML 引擎 解析 模板 ， 编 辑 模板 时 可 能 引入 大 量 人 为 错误 ， 
具备 设计 能 力 


























模板 系统 不 应 该 必须 在 WYSIWYG 编辑 器 (如 Dreamweaver) 中 才能 写 出 。 


够 灵活 。 


Django 的 目标 是 让 模板 编写 人 员 能 直接 
， 透 明 处 理 空格 


模板 系统 不 应 该 特殊 处 理 空格 。 模 板 中 的 空格 就 是 空格 ， 要 像 文本 那样 显示 出 
空格 都 应 该 显示 。 


， 不 重 造 一 门 编程 
模板 系统 一 定 





。 为 变量 赋 
。 编写 高 级 





We 


辑 HTML。 


























不 











的 逻辑 













































































处 理 模 





而 有 











板 有 很 多 额外 消耗 。 























长 。 不 在 模板 标签 中 





这 样 有 太 多 局 限 ， 句 法 不 





bee 


也 就 是 不 能 重 造 一 门 编程 语言 。 模 板 系统 的 目标 是 提供 适量 的 编程 功能 ， 例 如 分 支 和 循环 ， 足 够 做 表 

现 相 关 的 判断 就 行 。 

Django 模板 系统 知道 模板 最 常 由 设计 师 编 写 ， 而 不 是 程序 员 ， 因 此 不 要 求 具 备 Python 知识 。 
8， 安 全 保障 








模板 系统 默认 应 该 禁止 包含 恶意 代码 ， 例 如 删除 数据 库 记录 的 命令 。 
























































这 是 模板 系统 不 允许 随意 使 用 





























Python 代码 的 另 一 个 原因 。 
9， 可 扩展 
模板 系统 应 该 认识 到 ， 高 级 模板 编写 人 员 可 能 想 扩 展 功能 。 这 是 自 定 义 模板 标签 和 过 滤器 背后 的 理 
这 些 年 我 用 过 很 多 不 同 的 模板 系统 ， 这 种 设计 方式 真心 让 我 喜欢 。DTL 以 及 它 的 设计 方式 是 Django 框架 的 
主要 优势 之 一 。 





在 紧张 的 工作 节奏 
虎 ， 能 i 


中 ,设计 师 和 程序 员 积 极 沟通 ， 力 求 在 截止 日 
上 各 个 团队 关注 自己 擅长 做 的 事 。 

















期 之 前 完 











法 


头 





一 旦 你 在 





| 
| 














高 度 主观 性 ， 


每 出 现 一 种 新 的 模板 语言 ， 就 说 明 现 有 模板 语言 


Django 力求 成 为 全 栈 Web 框架 ， 











然 如 此 ， 但 是 Django 是 灵活 的 ， 它 不 要 
程序 员 对 此 有 不 同 的 观点 。 单 单 Python 一 门 语言 就 有 几 十 种 开源 的 模板 语言 ， 











成 工作 ， 此 时 Django 不 会 充当 拦路 





践 中 认识 到 这 一 点 ， 很 快 就 能 理解 为 什么 Django 是 “为 快 节 奏 完 美 主义 者 而 生 的 框架 ”。 








求 你 必须 使 用 DTL。 与 Web 应 

















能 满足 开发 者 的 需求 。 

















的 其 他 组 伯 














为 了 提升 Web 开发 者 的 工作 效率 ， 提 供 了 完整 的 组 件 ， 因 出 


EF 一样 ， 模 板 句 法 具有 
| 此 可 见 一 斑 。 

















上 多数 时 候 ， 使 
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用 DTL 更 为 便利 ， 但 这 绝 非 严格 要 求 。 


3.6 在 视图 中 使 用 模板 








我 们 已 经 学 习 了 模板 系统 的 基础 知识 ， 下 面 将 其 运用 到 视图 中 。 














回顾 一 下 前 一 章 在 mysite.views 模块 中 创建 的 current_datetime 视图 ， 如 下 所 示 : 


from django.http import HttpResponse 
import datetime 


def current datetime(request): 


now = datetime.datetime.now() 


html = "<html><body>It is now %s</body></html>" % now 


return HttpResponse(html) 


下 面 修改 这 个 视图 ， 让 它 使 用 Django 的 模板 系统 。 一 开始 你 可 能 会 想 这 么 做 : 


from django.template import Template, Context 
from django.http import HttpResponse 
import datetime 


def current datetime(request): 


now = datetime.datetime.now() 


t = Template("<html><body>It is now {{ current_date }}.</body></html>") 


html = t.render(Context({'current_date': now})) 
return HttpResponse(html) 


当然 ， 这 样 也 使 用 了 模板 系统 ， 但 是 这 没有 解决 我 们 在 本 章 开 头 指出 的 问题 ， 即 模板 仍然 髓 在 Python 代码 
中 ， 没 有 分 离 数据 和 表现 。 为 了 解决 这 个 问题 ， 我 们 要 把 模板 放 在 单独 的 文件 中 ， 然 后 让 视图 加 载 。 

















一 开始 你 可 能 会 考虑 把 模板 放 在 文件 系统 中 的 某 个 位 置 ， 然 后 使 




















j Python 内 置 的 文件 打开 功能 读 取 模 板 的 内 


容 。 假 设 模板 保存 在 /home/djangouser/templates/mytemplate.html 文件 中 ， 实 现 这 种 想法 的 代码 如 下 : 


from django.template import Template, Context 
from django.http import HttpResponse 
import datetime 


def current_datetime(request): 
now = datetime.datetime.now() 


# 使 用 文件 系统 中 模板 的 简单 方式 
# 这 样 做 不 好 ， 因 为 没有 考虑 缺少 文件 的 情况 


fp = open('/home/djangouser/tempLates/mytempLate.htmL' ) 


t = Template(fp.read()) 
fp.cLose() 


html = t.render(Context({'current_date': now})) 
return HttpResponse(html) 


然而 ， 这 么 做 不 够 优雅 ， 原因 如 下 : 
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。 没有 处 理 缺 少 文件 的 情况 。 如 果 mytemplate.html 文件 不 存在 或 不 可 读 ，open() 调用 会 抛 出 IOError 



































异常。 
。 模板 位 置 是 硬 编码 的 。 如 果 每 个 视图 函数 都 这 么 做 ， 要 重复 编写 模板 的 位 置 。 更 别提 要 输入 很 多 内 容 
了 ! 











。 有 大 量 乏 味 的 样板 代码 。 生 活 如 此 美好 ， 为 何 每 次 加 载 模板 时 要 浪费 时 间 编 写 open()、fp.read() 和 
fp.close() 调用 。 























为 了 解决 这 些 问题 ， 我 们 将 使 用 模板 加 载 机 制 ， 把 模板 放 在 专门 的 目录 中 。 





3.7 模板 加 载 机 制 


为 了 从 文件 系统 中 加 载 模板 ，Django 提供 了 便利 而 强大 的 API， 力 求 去 掉 模 板 加 载 调用 和 模板 自身 的 元 余 。 
若 想 使 用 这 个 模板 加 载 API， 首 先 要 告诉 框架 模板 的 存储 位 置 。 这 个 位 置 在 设置 文件 中 配置 ， 即 前 一 章 介绍 
ROOT_URLCONF 设置 时 提 到 的 settings.py 文件。 打开 settings.py 文件 ， 找 到 TEMPLATES 设置 。 它 的 值 是 一 个 
列表 ， 分 别针 对 各 个 模板 引擎 


















































TEMPLATES = [ 


{ 
'BACKEND': 'django.template.backends.django.DjangoTemplates', 
"DIRS YL |]:y 
'APP_DIRS': True， 
'OPTIONS': { 
# ... 一 些 选 项 
}, 
}, 


] 


BACKEND 的 值 是 一 个 点 分 Python 路 径 ， 指 向 实现 Django 模板 后 端 API 的 模板 引擎 类 。 内 置 的 后 端 有 djan- 
go.template.backends.django.DjangoTemplates 和 django. template.backends. jinja2.Jinja2。 














配置 包含 三 个 通用 的 设置 : 





并 


因为 多 数 引 警 从 文件 中 加 载 模板 ， 所 以 各 个 引擎 的 顶 














。 DIRS 定义 一 个 目录 列表 ， 模 板 引 擎 按 顺序 在 里 面 查找 模板 源 文 件 。 


。 APP_DIRS 设 定 是 否 在 安装 的 应 用 中 查找 模板 。 按 约定 ，APPS_DIRS 设 为 True 时 ，DjangoTemplates 会 在 
INSTALLED_APPS 中 的 各 个 应 用 里 查找 名 为 "templates” 的 子 目 录 。 这 样 ， 即 使 DIRS 为 空 ， 模 板 引擎 还 能 
查找 应 用 模板 。 


。 OPTIONS 是 一 些 针对 后 端的 设置 。 






























































同一 个 后 端 可 以 配置 具有 不 同 选 项 的 多 个 实例 ， 然 而 这 并 不 常见 。 此 时 ， 要 为 各 个 引擎 定义 唯一 的 NAME。 

















3.7.1 模板 目录 


DIRS 的 默认 值 是 一 个 空 列表 。 为 了 告诉 Django 的 模板 加 载 机 制 到 哪里 寻找 模板 ， 选 择 一 个 选 保 存 模板 的 目 
录 ， 把 它 添加 到 DIRS 中 ， 像 下 面 这 样 ; 























'DIRS': [ 
'/home/html/example.com', 
'/home/html/default', 
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。 如 果 不 是 构建 没有 应 用 的 极 简 程 序 ， 最 好 留 空 DIRS。 设 置 文件 默认 把 APP_DIRS 设 为 True， 因 此 最 好 





在 Django 应 用 上 








。 如 果 想 在 项 目 根 目录 中 放 一 些 主 模板 (例如 在 mysite/templates 目录 


'DIRS': [os.path.join(BASE_DIR, 'templates')], 





Pp 放 一 个 “templates” 子 目录 。 














Sr 


， 需 要 像 这 样 设 定 DIRS : 


。 模板 目录 不 一 定 非得 叫 'templates' ，Django 不 限制 你 用 什么 名 称 ， 但 是 坚守 约定 易于 理解 项 目的 结 





构 。 如 果 不 想 遵 
器 的 用 户 有 权 读 

















守 这 个 约定 ， 或 者 出 于 某 些 原因 不 能 这 么 做 ， 可 以 指定 任何 目 





取 那 个 目录 中 的 模板 就 行 。 























录 ， 只 要 启动 Web 服务 


。 在 Windows 中 要 加 上 盘 符 ， 而 且 要 使 用 Unix 风格 的 正 斜 线 ， 而 不 是 反 斜 线 ， 如 下 所 示 : 


'DIRS': ['C:/www/django/templates'], 








我 们 还 未 创建 Django 应 用 ， 因 此 为 了 让 下 面 的 代码 
[os.path.join(BASE_DIR，tempLates')]。 设 定好 DIRS 之 后 ， 要 修改 视图 代码 ， 让 它 使 
机 制 ， 而 不 是 硬 编码 模板 的 路 径 。 





from django.tempLate.Loader import get_tempLate 
































from django.template import Context 
from django.http import HttpResponse 


import datetime 


def current_datetime(request): 


now = datetime.datetime.now() 


t = get templatel('current datetime.html') 
html = t.render(Context({'current_date': now})) 


return HttpResponse(html) 


这 里 ， 我 们 把 手动 从 文件 系统 
这 个 函数 的 参数 是 模板 的 名 称 ， 找 到 模板 在 文件 系统 





























对 象 。 这 里 使 用 的 模板 是 current_datetime.html，.html 扩展 名 没什么 特别 之 处 ， 只 











扩展 名 随便 用 ， 甚 至 可 以 完全 省 略 。 





为 了 找到 模板 在 文件 系统 


。 如 果 APP_DIRS 的 值 是 True， 而 且 使 用 DTL， 在 当 
。 如 果 在 当前 应 用 中 没 找到 模板 ，get_template() 于 

















常 运 行 ， 要 把 DIRS 设 为 
































回 到 current_datetime 视图 ， 寺 





它 改 成 下 面 这 样 : 


PpP 加 载 模 板 的 代码 改 成 了 django.tempLate.Loader .get_tempLate() 了 匈 数 调用 。 
的 位 置 后 ， 打 开 那 个 文件 ， 编 译 后 返回 一 个 Template 











的 位 置 ，get_tempLate() 按 下 列 顺序 查找 : 











PpP 查 找 “templates” 目 
传 给 它 的 模板 名 称 添加 到 DIRS 中 的 各 个 目录 后 再 

















] Django 的 模板 加 载 




















尔 觉得 合适 ， 模 板 的 

















按 顺序 在 各 个 目录 中 查找 。 假 如 DIRS 的 第 一 个 元 素 是 '/home/django/mysite/templates' ， 上 述 
get_template() 调用 查找 的 模板 是 /home/django/mysite/templates/current_datetime.html。 








。 如 果 get_template() 找 不 到 指定 名 称 对 应 的 模板 ， 抛 








为 了 查看 模板 异常 是 什么 样子 ， 在 Django 项 目的 目录 中 运行 python manage.py runserver， 启 动 Django 开发 
服务 器 。 然 后 ， 在 浏览 器 中 访问 激活 current_datetime 视 





DEBUG 设置 的 值 是 True， 











现 TemplateDoesNotExist 错误 (图 3-1) 。 





H TemplateDoesNotExist 异 














党 





门 o 








的 页 面 (http://127.0.0.1:8000/time/) 。 假 设 
而 且 没 有 创建 current_datetime.html 模板 ， 应 该 会 看 到 Django 错误 页 面 ， 指 明 出 
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BD TemplateDoesNotExist at x 


€ CG 省 | D127.0.0.1:8000/time, @ O \ 避 三 


TemplateDoesNotExist at /time/ 


current_datetime.html 


Request Method: GET 

Request URL: http://127.0.0.1:8000/time/ 
Django Version: 1.9.7 
Exception Type: TemplateDoesNotExist 
Exception Value: current_datetime.html 


Exception Location: C:\Users\NigeN\OneDrive\Documents\Visual Studio 
2015\Projects\imysite\mysite\env\lib\site-packages\django\template\loader.py in 
get_template, line 43 

Python Executable: C:\Users\Nigel\OneDrive\Documents\Visual Studio 
2015\Projects\imysite\mysite\env\Scripts\python.exe 


Python Version: 3.4.3 


Python Path: ['C:\\Users\\Nigel\\OneDrive\\Documents\\Visual Studio ' 
"2815\\Projects\\mysite\\mysite’, 
“'C:\\WINDOWS\\SYSTEM32\\python34 .zip', 
'C:\\Users\\Nigel\\OneDrive\\Documents\\Visual Studio ' 
"2815\\Projects\\mysite\\mysite\\env\\DLLs', 
'C:\\Users\\Nigel\\OneDrive\\Documents\\Visual Studio ' 
"2815\\Projects\\mysite\\mysite\\env\\1ib', 
'C:\\Users\\Nigel\\OneDrive\\Documents\\Visual Studio " 
"2815\\Projects\\mysite\\mysite\\env\\Scripts', 
'C:\\Python34\\Lib", 

'C:\\Python34\\DLLs', 
"C:\\Users\\Nigel\\OneDrive\\Documents\\Visual Studio ' 
"2815\\Projects\\mysite\\mysite\\env', 
'C:\\Users\\Nigel\\OneDrive\\Documents\\Visual Studio ' 
"2815\\Projects\\mysite\\mysite\\env\\lib\\site-packages'] 


Server time: Tue,7 Jun 2016 15:39:59 +1000 


Template-loader postmortem 
图 3-1， 缺少 模 板 的 错误 页 面 


这 个 错误 页 面 与 第 2 章 说 明 的 那个 类 似 ， 不 过 多 了 一 部 分 调试 信息 :“Template-loader postmortem”。 这 部 分 
信息 指出 Django 尝试 加 载 了 哪些 模板 ， 以 及 失败 的 原因 (例如 ，“File does not exist*) 。 调 试 模板 加 载 错误 
时 ， 这 些 信 息 很 有 价值 。 接 下 来 ， 创 建 current_datetime.html 文件 ， 写 人 下 述 模 板 代码 : 





It is now {{ current_date }}. 








把 这 个 文件 保存 到 mysite/templates 目录 中 (如 果 没 有 “templates” 目 录 ， 创 建 一 个 ) 。 然 后 在 Web 浏览 器 中 
刷新 页 面 ， 此 时 应 该 能 看 到 正确 演 染 的 页 面 。 








3.8 render() 


至 此 ， 我 们 知道 如 何 加 载 模板 、 填 充 上 下 文 、 返 回 HttpResponse 对 象 了 ， 这 么 做 的 结果 是 泻 染 一 个 模板 。 随 
后 ， 我 们 优化 了 视图 ， 使 用 get_template() 替换 硬 编 码 的 模板 路 径 。 我 这 么 做 是 为 了 让 你 了 解 Django 加 载 
及 在 浏览 器 中 泻 染 模板 的 过 程 。 


其 实 ，Django 为 此 提供 了 更 为 简单 的 方式 。Django 的 开发 者 意识 到 这 是 一 个 常见 的 任务 ， 因 此 需要 一 种 简单 
的 方式 ， 只 需 一 行 代码 就 能 做 到 。 这 个 简单 方式 是 django.shortcuts 模块 中 名 为 render() 的 函数 。 





























多 数 时 候 人 们 都 使 用 render()， 而 不 自己 动手 加 载 模 板 、 创 建 Context 和 HttpResponse 对 象 一 一 除非 雇主 以 
代码 行 数 评判 你 的 工作 。 
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下 面 是 使 用 render() 重 写 的 current_datetime 视图 : 











from django.shortcuts import render 
import datetime 


def current_datetime(request) : 
now = datetime.datetime.now() 
return render(request, 'current datetinme.html', {'current date': now}) 





差别 多 么 明显 啊 ! 下 面 详细 说 明 这 次 改动 : 














。 不 用 再 导入 get_template、Template、Context 或 HttpResponse 了 ， 而 要 导入 django.shortcuts.ren- 
der。import datetime 不 变 。 


。 在 current_datetime 函数 中 ， 仍 然 要 计算 now， 不 过 加 载 模板 、 创 建 上 下 文 、 泻 染 模 板 和 创建 HttpRe- 
sponse 对 象 全 由 render() 调用 代替 了 。Frender() 的 返回 值 是 一 个 HttpResponse 对 象 ， 因 此 在 视图 中 
可 以 直接 返回 那个 值 。 






































render() 的 第 一 个 参数 是 请 求 对 象 ， 第 二 个 参数 是 模板 名 称 ， 第 三 个 单数 可 选 ， 是 一 个 字段 ， 用 于 创建 传 给 
模板 的 上 下 文 。 如 果 不 指定 第 三 个 参数 ，render() 使 用 一 个 空 字典 。 














3.9 模板 子 目录 




















如 果 把 所 有 模板 存放 在 一 个 目录 中 ， 很 快 就 会 变 得 不 灵 便 。 你 可 能 想 把 模板 存储 在 模板 目录 的 子 目录 里 ， 这 
么 做 很 好 。 


其 实 ， 我 也 推荐 这 么 做 ， 因 为 有 些 高 级 的 Django 功能 (例如 第 10 章 将 说 明 的 通用 视图 系统 ) 默认 预期 这 种 
模板 布局 方式 。 


把 模板 放 到 模板 目录 的 子 目录 中 不 是 难事 。 调 用 get_template() 时 ， 只 需 在 模板 名 称 前 面 加 上 子 目录 的 名 称 
和 一 条 斜 线 ， 如 下 所 示 : 




















t = get template('dateapp/current datetime.html') 


render() 是 对 get_template() 的 简单 包装 ， 因 此 在 render() 的 第 二 个 参数 中 也 可 以 这 么 做 ， 如 下 所 示 : 





return render(request, 'dateapp/current datetime.html', {'current_date': now}) 


子 目录 的 层级 深度 没有 限制 ， 可 以 根据 需要 尽情 使 用 。 


Windows 用 户 注意 ， 要 使 用 正和 斜 线 ， 而 非 反 斜 线 。get_template() 要 求 Unix 风格 的 文件 名 。 




















3.10 include 模板 标签 














说 完 模 板 加 载 机制 之 后 ， 可 以 介绍 利用 这 一 机 制 的 一 个 内 置 模板 标签 了 : {% inctude 加 。 


这 个 标签 的 作用 是 引入 另 一 个 模板 的 内 容 。 它 的 参数 是 要 引入 的 模板 的 名 称 ， 可 以 是 变量 ， 也 可 以 是 硬 编码 
的 字符 串 〈 放 在 引号 里 ， 单 双 引 号 都 行 ) 。 


只 要 想 在 多 个 模板 中 使 用 相同 的 代码 ， 就 可 以 考虑 使 用 {% inctude 时 ， 去 除 重复 。 下 面 两 个 示例 引入 
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nav.html 模板 的 内 容 。 二 者 的 作用 相同 ， 目 的 是 说 明 既 可 以 使 用 单 引号 ， 也 可 以 使 用 双 引 号 。 


{% include 'nav.html' %} 
{% include "nav.html" %} 


下 述 示例 引入 incLudes/nav.htmlt 模板 的 内 容 : 
{% include 'includes/nav.html' %} 

下 述 示例 引入 的 模板 名 称 由 变量 template_name 指定 : 
{% include tempLate_name %} 


与 get_template() 一 样 ，include 标签 的 参数 指定 的 模板 在 当前 Django 应 用 的 "templates” 目 录 中 (APPS_DIR 
为 True 时 ) ， 或 者 在 DIRS 设置 的 目录 中 。 引 入 的 模板 在 引入 它 的 模板 的 上 下 文中 执行 。 


来 看 下 面 两 个 模板 : 





# mypage.html 


<html> 

<body> 
{% include "includes/nav.html" %} 
<h1>{{ title }}</h1> 

</body> 

</htmL> 


# includes/nav.html 


<div id="nav"> 
You are in: {{ current_ section }} 
</div> 


如 果 演 染 mypage.html 时 使 用 的 上 下 文中 有 current_section， 那 么 它 可 以 作为 变量 在 引入 的 模板 中 使 用 一 一 
这 与 我 们 预期 的 一 样 。 


如 果 {% inctude %) 标签 的 参数 指定 的 模板 不 存在 ，Django 会 做 下 面 两 件 事 中 的 一 件 : 








。 DEBUG 为 True 时 ， 泻 染 Django 错误 页 面 ， 显 示 TemplateDoesNotExist 异常 。 
。 DEBUG 为 False 时 ， 静 默 ， 那 个 标签 的 位 置 什 么 也 不 显示 。 


| 


引入 的 模板 之 间 没 有 共享 的 状态 ， 每 次 引入 都 是 完全 独立 的 泻 染 过 程 。 块 在 引入 之 前 运行 。 这 
意味 着 ， 从 另 一 个 模板 中 引入 的 块 已 经 执行 并 泻 染 了 ， 不 能 在 引入 它 的 模板 中 覆盖 。 











3.11 模板 继承 


目前 ， 我 们 举 的 示例 都 是 简短 的 HTML 片段 ， 但 是 在 真实 世界 中 ， 你 将 使 用 Django 的 模板 系统 创建 整个 
HTML 页 面 。 这 就 引出 Web 开发 常见 的 一 个 问题 ， 在 整个 网 站 中 ， 如 何 减少 通用 页 面 区 域 (如 全 站 导航 ) 的 
重复 和 元 余 ? 
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这 个 问题 一 种 典型 的 解决 方法 是 使 用 服务 器 端 引 入 ， 即 在 HTML 页 首 
| 说 过 的 人 % include %} 模板 标签 。 





Django 支持 这 个 方法 ， 即 使 用 前 和 


但 是 ， 在 Django 中 解决 这 个 问题 更 好 的 
个 基底 “骨架 "模板 ， 包 含 网 站 的 所 有 通 



































方法 是 使 用 模板 继承 ,这样 更 优雅 。 大 致 来 
部 分 ， 并 且 定 义 一 些 “ 块 "， 让 子 模板 覆盖 。 下 夯 





i 中 使 用 指令 “引入 ” 男 一 个 网 页 。 其 实 ， 




















， 模 板 继承 是 指 创 建 一 
i 举 个 例子 。 编 辑 



































current_datetime.html 文件 ， 为 current_datetime 视图 创建 更 为 完整 的 模板 : 


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> 


<html lang="en"> 


<head> 
<title>The current time</title> 
</head> 
<body> 
<hi>My helpful timestamp site</h1> 
<p>It is now {{ current_date }}.</p> 


<hr> 

<p>Thanks for visiting my site.</p> 
</body> 
</htmL> 





这 看 起 来 没什么 问题 ， 但 是 如 果 要 为 另 一 个 视图 创建 模板 
想 编写 一 个 精美 有 效 的 完整 HTML 模板 ， 要 这 人 么 做 : 








已? 比如 第 2 章 编写 的 hours_ahead 视图 。 如 果 还 


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> 


<html lang="en"> 


<head> 
<title>Future time</title> 
</head> 
<body> 
<hi>My helpful timestamp site</h1> 


<p> 


In {{ hour_offset }} hour(s), it will be {{ next_ time }}. 


</p> 


<hr> 

<p>Thanks for visiting my site.</p> 
</body> 
</htmL> 





显然 ， 刚 刚 重复 编写 了 大 量 HTML。 想 象 一 下 ， 典 型 的 网 站 包含 导航 栏 、 几 个 样式 表 ， 可 能 还 有 

















JavaScript， 这 得 在 各 个 模板 中 编写 多 少 重复 的 HIML 啊 ! 























服务 器 端 引 入 方案 解决 这 个 问题 的 方法 是 把 模板 中 通 





的 部 分 提取 出 来 ， 保 存 到 单独 的 模板 中 ， 然 后 再 引入 


各 个 模板 。 或 许可 以 把 模板 顶部 那 部 分 保存 在 header .htmt 文件 中 : 





<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> 


<html lang="en"> 
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<head> 


把 底部 保存 在 footer .htmt 文件 中 : 


<hr> 
<p>Thanks for visiting my site.</p> 
</body> 

</html> 



































采用 这 种 方式 ， 页 头 和 页 脚 处 理 起 来 很 容易 ， 真 正 难处 理 的 是 中 间 部 分 。 这 里 ， 两 个 页 面 都 有 同一 个 标 头 
(“My helpful timestamp site”) ， 但 是 不 能 把 它 放 在 header .html 文件 中 ， 因 为 两 个 页 面 的 标题 不 同 。 如 果 把 
那个 标 头 放 在 页 头 中 ， 标 题 也 在 其 中 ， 这 样 就 不 能 在 各 个 页 面 中 定制 标题 了 。 


Django 的 模板 继承 系统 能 解决 这 样 的 问题 。 你 可 以 把 它 理解 为 服务 器 端 引入 的 相反 版 本 。 我 们 不 再 定义 通用 
的 片段 ， 而 是 定义 有 区 别 的 片段 。 


首先 ， 要 定义 一 个 基 模 板 ， 即 一 个 骨架 ， 供 子 模板 填充 。 下 面 是 针对 前 述 示 例 的 基 模 板 : 




































































<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> 
<html lang="en"> 


<head> 

<title>{% block title %}{% endblock %}</title> 
</head> 
<body> 

<hi>My helpful timestamp site</h1> 

{% block content %}{% endblock %} 


{% block footer %} 
<hr> 
<p>Thanks for visiting my site.</p> 
{% endblock %} 
</body> 
</htmL> 


我 们 把 这 个 模板 命名 为 base.htmL， 它 定义 了 一 个 简单 的 HTML 文档 骨架 ， 供 网 站 中 的 所 有 页 面 使 用 。 





子 模板 可 以 覆盖 块 的 内 容 、 向 块 中 添加 内 容 ， 或 者 原封 不 动 。 (如 果 你 一 直 跟 着 做 ， 请 把 这 个 文件 保存 到 模 
板 目 录 中 ， 命 名 为 base.html。) 


这 里 用 到 一 个 你 没 见 过 的 模板 标签 : {% block 寻 。 它 的 作用 很 简单 ， 告 诉 模板 引擎 ， 子 模板 可 以 覆盖 这 部 分 
内 容 。 


创建 好 基 模 板 之 后 ， 修 改 现 有 的 current_datetime.html 模板 ， 让 它 使 用 基 模 板 : 























{% extends "base.html" %} 
{% block title %}The current time{% endblock %} 
{% block content %} 


<p>It is now {{ current_date }}.</p> 
{% endblock %} 











此 外 ， 再 为 第 3 章 编写 的 hours_ahead 视图 创建 一 个 模板 吧 。( 把 hours_ahead 视图 中 硬 编码 的 HTML 改 为 使 
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用 模板 系统 这 个 任务 留 给 你 去 做 。) 下 面 是 这 个 模板 的 代码 : 


{% extends "ba 


se.html" %} 


{% block title %}Future time{% endblock %} 


{% block conte 


<p> 


nt %} 


In {{ hour_offset }} hour(s), it will be {{ next_ time }}. 


</p> 
{% endblock %} 


这 样 是 不 是 很 棒 ? 各 个 模板 只 
base.htmL， 其 他 所 有 模板 都 能 立即 体现 出 变化 。 














包含 自己 专用 的 代码 ， 没 有 元 余 。 如 果 想 修改 全 站 的 设计 ， 只 需 修 改 




















下 面 说 说 原理 。 模 板 引 警 加载 current_datetime.html 模板 时 ， 发 现 有 {% extends %} 标签 ， 意 识 到 这 是 一 个 





子 模板 ， 因 此 立即 力 





[ 载 父 模板 ， 即 这 上 





的 base.html。 


加 载 父 模板 时 ， 模 板 引 警 发 现 base.html 中 有 三 个 {% block 六 标签， 然后 使 用 子 模板 中 的 内 容 蔡 换 。 因 此 ， 
将 使 用 {% block title %} 中 定义 的 标题 和 {% block content %} 中 定义 的 内 容 。 


注意 ， 这 个 子 模板 没有 定义 footer 块 ， 因 此 模板 系统 使 用 父 模板 中 的 内 容 。 父 模板 中 的 {% block 9 块 总 是 


后 备 内 容 。 














继承 不 影响 模板 的 上 下 文 。 也 就 是 说 ， 继 承 树 中 的 任何 模板 都 能 访问 上 下 文中 的 每 一 个 模板 变量 。 根 据 需 








要 ， 继 承 层级 的 深度 不 限 。 继 承 经 常 使 用 下 述 三 层 结构 : 








1. 创建 base.html 模板 ， 定 义 网 站 的 整体 外 观 。 这 个 模板 的 内 容 很 少 变化 。 
2.， 为 网 站 中 的 各 个 “区 域 ”" 创 建 base_SECTION.html 模板 (如 base_photos.html 和 base_forum.html) 。 这 
些 模板 扩展 base.htmL， 包 含 各 区 域 专属 的 样式 和 设计 。 








3， 为 各 种 页 面 创建 











站 独 的 模板 ， 例 如 论坛 页 面 或 相册 。 这 些 模 板 扩 展 相 应 的 区 域 模板 。 

















TY 





这 种 方式 能 最 好 地 复 用 代码 ， 而 且 便 了 





























下 面 是 使 用 模板 继承 的 一 些 指导 方针 : 
































为 共享 的 区 域 添加 内 容 ， 例 如 同一 个 区 域 通用 的 导航 。 








。 如 果 模 板 中 有 {% extends 准 ， 必 须 是 模板 中 的 第 一 个 标签 。 否 则 ， 模 板 继 承 不 起 作用 。 
。 一 般 来 说 ， 基 模板 中 的 {% block 标签 越 多 越 好 。 记 住 ， 子 模板 无 需 定义 父 模板 中 的 全 部 块 ， 因 此 


可 以 为 一 些 块 定义 合理 











。 如 果 发 现 要 在 多 个 模板 中 重复 
block %} 标签 里 。 


。 如 果 需 要 从 父 模板 中 的 块 里 获取 内 容 ， 使 用 {{ block.super }}， 这 是 一 个 “魔法 "变量 ， 提 供 父 模板 中 





的 默认 内 容 ， 只 在 子 模板 中 履 盖 需要 的 块 。 钧 子 多 总 是 好 的 。 
































写 相同 的 代码 ， 或 许 说 明 应 该 把 那些 代码 移 到 父 模板 中 的 一 个 {% 























UD 

















演 染 后 的 文本 。 向 块 中 添加 内 容 ， 而 不 是 完全 覆盖 时 就 可 以 这 么 做 。 

。 在 同一 个 模板 中 不 能 为 多 个 {% 
签 是 双向 的 。 即 ，block 标签 不 仪 标识 供 填充 的 空位 ， 还 用 于 定义 填充 父 模板 中 空位 的 内 容 。 如 果 一 
个 模板 中 有 两 个 同名 的 块 ， 那 么 父 模板 就 不 知道 使 用 哪个 块 里 的 内 容 。 


。 传 给 {% extends %} 的 模板 名 称 使 用 与 get_template() 相同 的 方法 加 载 。 即 ， 模 板 在 DIRS 设置 定义 的 























block %} 标签 定义 相同 的 名 称 。 之 所 以 有 这 个 限制 ， 是 因为 block 标 











目录 中 ， 或 者 在 当前 Django 应 用 的 "templates" 目 录 里 。 




















。 多 数 情况 下 ，{% extends % 的 参数 是 字符 串 ， 不 过 如 果 直 到 运行 时 才 知 道 父 模板 的 名 称 ， 也 可 以 用 变 
量 。 通 过 这 一 点 可 以 做 些 动态 判断 。 
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3.12 接 下 来 





现在 ， 你 掌握 了 Django 模板 系统 的 基础 知识 ， 接 下 来 呢 ? 多 数 现代 的 网 站 是 数据 库 驱 动 的 ， 即 网 站 的 内 容 存 
储 在 关系 数据 库 中 。 这 把 数据 和 逮 辑 明确 区 分 开 了 “与 视图 和 模板 把 逻辑 和 表现 分 开 是 一 个 道理 ) 。 下 一 章 
介绍 Django 提供 的 与 数据 库 交 互 的 工具 。 
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第 4 章 Django 模型 





第 2 章 涵盖 了 使 用 Django 构建 动态 网 站 的 基础 ， 即 设置 视图 和 URL 配置 。 如 前 所 述 ， 视 图 负责 执行 逻辑 ， 
然后 返回 响应 。 在 所 举 的 示例 中 ， 有 一 个 的 逻辑 是 计算 当前 日 期 和 时 间 。 


对 现代 的 Web 应 用 程序 而 言 ， 视 图 逻辑 经 常 需要 与 数据 库 交 互 。 在 数据 库 驱 动 型 网 站 中 ， 网 站 连接 数据 库 服 
务 器 ， 从 中 检索 数据 ， 然 后 在 网 页 中 把 数据 显示 出 来 。 此 外 ， 可 能 还 会 提供 让 访客 自行 填充 数据 库 的 方式 。 









































很 多 复杂 的 网 站 都 兼 具 这 两 种 操作 。 亚 马 逊 网 站 就 是 数据 库 驱 动 型 网 站 ， 每 个 商品 页 面 其 实 都 会 查询 亚马逊 
的 商品 数据 库 ， 然 后 把 数据 以 HTML 格式 显示 出 来 ， 顾 客 发 表 评 论 时 ， 把 评论 插入 相应 的 数据 库 表 中 。 


Django 非常 适合 构建 数据 库 驱 动 型 网 站 ， 它 提供 了 简单 而 强大 的 工具 ， 易 于 使 用 Python 执行 数据 库 查 询 。 
本 章 就 说 明 这 个 功能 ， 即 Django 的 数据 库 层 。 


严格 来 说 ， 使 用 Django 的 数据 库 层 不 必 知道 基 本 的 关系 数据 库 理 论 和 SQL， 但 是 强烈 建议 你 
掌握 一 些 这 方面 的 知识 。 本 书 不 会 涉及 这 些 知 识 ， 但 是 就 算 你 是 数据 库 新 手 ， 也 可 以 继续 往 下 
读 ， 说 不 定 在 这 个 过 程 中 你 能 掌握 一 些 呢 。 






























































4.1 在 视图 中 执行 数据 库 查询 的 " 蚌 春 方式 


第 2 章 详 述 了 在 视图 中 生成 输出 的 "思春 "方式 (直接 在 视图 中 硬 编码 文本 ) ， 同 样 ， 在 视图 中 从 数据 库 里 检 
索 数据 也 有 ”愚蠢 "方式 。 这 种 方式 很 简单 : 使 用 现 有 的 Python 库 执行 SQL 查询 ， 然 后 处 理 结果 。 在 下 面 这 
个 示例 中 ， 我 们 使 用 MysQLdb 库 连 接 一 个 MySQL 数据 库 ， 检 索 一 些 记录 ， 提 供给 模板 ， 在 网 页 中 显示 : 




















from django.shortcuts import render 
import MySQLdb 


def book_ list(request): 
db = MySQLdb.connect(uyser='me', db='mydb', passwd='secret', host='localhost') 
cursor = db.cursor() 
cursor.execute('SELECT name FROM books ORDER BY name') 
names = [row[0] for row in cursor.fetchall()] 
db.close() 
return render(request, 'book list.html', {f'names': names}) 





这 么 做 是 可 以 ， 但 是 很 快 就 会 出 现 一 些 问题 : 


。 数据 库 连接 参数 是 硬 编码 的 。 理 想 的 做 法 是 ， 把 这 些 参 数 存储 在 Django 配置 中 。 

。 要 编写 相当 多 的 样板 代码 : 建立 连接 、 创 建 游标 、 执 行 语句 、 关 闭 连接 。 理 想 情 况 下 ， 我 们 只 应 该 指 
定 想 要 什么 结果 。 

。 与 MySQL 耦合 。 如 果 以 后 想 从 MySQL 转 到 PostgreSQL， 要 重新 编写 大 量 代 码 。 理 想 情况 下 ， 数 据 
库 服 务 器 应 该 有 一 层 抽象 ， 这 样 在 一 处 修改 就 能 更 换 。 (如 果 构 建 的 是 开源 Django 应 用 程序 ， 希望 有 
更 多 的 人 使 用 ， 这 个 特性 尤其 有 用 。 ) 
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正如 你 期 竺 的 那样 ，Dijango 的 数据 库 层 解决 了 这 些 问题 。 


4.2 配置 数据 库 














了 解 基本 原理 之 后 ， 下 面 来 讨论 Django 的 数据 库 层 。 首 先 ， 看 一 下 创建 应 用 程序 时 在 settings.py 文件 中 添 
加 的 初始 配置 




















# Database 
六 
DATABASES = { 
'default': { 
'ENGINE': 'django.db.backends.sqlite3', 
'NAME': os.path.join(BASE_DIR, 'db.sqlite3'), 


} 


默认 的 设置 非常 简 











I 





和 站， 下 面 说 明 各 个 设置 : 
































。 ENGINE 告诉 Django 使 用 哪个 数据 库 引 擎 。 本 书 的 示例 使 用 SQLite， 因 此 不 用 改 ， 继 续 使 用 默认 的 
django.db.backends.sqLite3。 


。 NAME 告诉 Django 数据 库 的 名 称 。 例 如 : 'NAME' : 'mydb',。 














因为 我 们 使 用 的 是 SQLite，startproject 命令 为 我 们 填 上 了 数据 库 文件 的 完整 文件 系统 路 径 。 


这 是 默认 设置 ， 对 这 本 书 中 的 代码 来 说 ， 无 需 修改 。 这 里 讲解 这 些 设置 ， 是 为 了 让 你 了 解 在 Django 中 配置 数 
据 库 是 多 么 简单 。 第 21 章 将 详细 说 明 如 何 配 置 Django 支持 的 各 种 数据 库 。 




































































4.3 第 一 个 应 用 
确认 可 以 连接 数据 库 之 后 ， 接 下 来 我 们 将 创建 一 个 Django 应 用 一 一 一 系列 Django 代码 ， 包 含 模型 和 视图 ， 















































打包 在 一 个 独立 的 Python 包 里 ， 表 示 一 个 完整 的 Django 应 用 程序 。 这 里 有 必要 澄清 一 下 术语 ， 因 为 初学 者 
容易 弄 混 。 我 们 在 第 1 章 创建 了 一 个 项 目 ， 那 么 项 目 与 应 用 之 间 有 什么 区 别 呢 ? 区 别 是 一 个 是 配置 ， 一 个 是 
代码 。 









































。 一 个 项 目 是 一 系列 Django 应 用 的 实例 ， 外 加 那些 应 用 的 配置 。 严 格 来 说 ， 一 个 项 目 唯一 需要 的 是 一 个 
设 定 文件 ， 定 义 数据 库 连 接 信息 、 安 装 的 应 用 列表 、DIRS， 等 等 。 
。 一 个 应 用 是 一 系列 便携 的 Django 功能 ， 通 常 包 含 模 型 和 视图 。 打 包 在 一 个 Python 包 里 。Django 自 带 
了 一 些 应 用 ， 例 如 管理 后 台 。 这 些 应 用 的 独特 之 处 是 便携 ， 可 以 在 多 个 项 目 中 复 用 。 













































































你 编写 的 代码 在 这 二 者 之 间 游 走 ， 没 有 严格 的 界限 。 如 果 构 建 的 是 简单 的 网 站 ， 可 能 只 会 使 用 一 个 应 用 ， 如 
果 构 建 复杂 的 网 站 ， 有 几 个 不 相关 的 部 分 ， 如 电 商 系统 和 留言 板 ， 可 能 想 把 各 部 分 放 在 单独 的 应 用 中 ， 这 样 
以 后 可 以 复 用 。 


其 实 ， 并 非 一 定 要 创建 应 用 ， 本 书目 前 所 举 的 视图 函数 示例 都 没 这 么 做 ， 而 是 创建 一 个 名 为 views.py 的 文 
件 ， 在 里 面 编 写 视图 函数 ， 然 后 把 URL 配置 指向 那些 函数 。 没 有 任何 “应 用 ”是 必须 的 。 





































































































然而 ， 在 应 用 方面 有 个 严守 的 约定 : 如 果 使 用 Django 的 数据 库 层 (模型 ) ， 必 须 创建 Django 应 用 。 模 型 必 
须 保存 在 应 用 中 。 因 此 ， 编 写 模型 之 前 ， 要 新 建 一 个 应 用 。 












































在 mysite 项 目 目录 (manage.py 文件 所 在 的 目录 ， 不 是 mysite 应 用 目录 ) 里 输入 下 述 命令 创建 books 应 用 : 
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python manage.py startapp books 





这 个 命令 没有 输出 ， 不 过 却 会 在 mysite 目录 中 创建 books 子 目 录 。 我 们 来 看 一 下 那个 目录 的 内 容 : 








books/ 
/migrations 
__init .py 
admin.py 
models.py 
tests.py 
Views.py 














这 个 应 用 的 模型 和 视图 就 保存 在 这 些 文件 中 。 在 你 喜欢 的 文本 编辑 器 中 看 一 下 models.py 和 views.py 文件 的 
内 容 。 这 两 个 文件 除了 一 个 导入 语句 和 一 行 注释 之 外 ， 没 有 其 他 内 容 。 这 是 Django 应 用 的 胃 新 起 点 。 





























4.4 使 用 Python 定义 模型 











第 1 章 说 过 ,“MTV” 中 的 “M" 表 示 “Model”( 模 型 。Django 模型 是 使 用 Python 代码 对 数据 库 中 数据 的 描 
述 ， 是 数据 的 结构 ， 等 效 于 SQL 中 的 CREATE TABLE 语句 ， 不 过 是 用 Python 代码 而 非 SQL 表述 的 ， 而 且 不 仅 
包含 数据 库 列 的 定义 。 


Django 通过 模型 在 背后 执行 SQL， 返回 便利 的 Python 数据 结构 ， 表 示 数 据 库 表 中 的 行 。Django 还 通过 模型 
表示 SQL 无 法 处 理 的 高 层级 概念 。 


如 果 熟 悉数 据 库 ， 你 的 第 一 反应 可 能 是 :“ 使 用 Python 代替 SQL 定义 数据 模型 是 不 是 多 此 一 举 ? "Django 之 
所 以 这 么 做 有 几 个 原因 : 







































































。 内 省 (introspection) 有 开销 ， 而 且 不 完美 。 为 了 提供 便利 的 数据 访问 API，Django 需要 以 某 种 方式 知 
晓 数据 库 布局 ， 而 这 一 需求 有 两 种 实现 方式 。 第 一 种 是 使 用 Python 明确 描述 数据 ， 第 二 种 是 在 运行 时 
内 省 数据 库 ， 推 知 数据 模型 。 第 二 种 方式 在 一 个 地 方 存储 表 的 元 数据 ， 看 似 更 简单 ， 其 实 会 导致 几 个 
问题 。 首 先 ， 运 行 时 内 省 数据 库 肯 定 有 消耗 。 如 果 每 次 执行 请 求 ， 或 者 只 是 初始 化 Web 服务 器 都 要 内 

省 数据 库 ， 那 带 来 的 消耗 是 无 法 接受 的 。 (有些 人 觉得 那 点 消耗 不 算 事 ， 然 而 Django 的 开发 者 可 是 在 
想方设法 努力 降低 框架 的 消耗 。) 其 次 ， 有 些 数据 库 ， 尤 其 是 旧版 MySQL， 存 储 的 元 数据 不 足以 完 
成 内 省 。 

。 Python 编写 起 来 让 人 心情 和 舒畅， 而且 使 用 Python 编写 所 有 代码 无 需 频 繁 让 大 脑 切换 情境 。 

在 一 个 编程 环境 (思维 ) 中 待 久 了 ， 有 助 于 提升 效率 。 在 SQL 和 Python 之 间 换 来 换 去 容易 打 断 状 


六 
/PNo 


。 把 数据 模型 保存 在 代码 中 比 保存 在 数据 库 中 易于 做 版 本 控制 ， 易 于 跟踪 数据 布局 的 变化 。 


。 SQL 对 数据 布局 的 元 数据 只 有 部 分 支持 。 例 如 ， 多 数 数 据 库 系 统 没 有 提供 专门 表示 电子 邮件 地 址 或 
URL 的 数据 类 型 。 而 Django 模型 有 。 高 层级 的 数据 结构 有 助 于 提升 效率 ， 让 代码 更 便于 复 用 。 


。 不 同 数据 库 平 台 使 用 的 SQL 不 一 致 。 


分 发 Web 应 用 程序 时 ， 更 务实 的 做 法 是 分 发 一 个 描述 数据 布局 的 Python 模块 ， 而 不 是 分 别针 对 
MySQL、PostgreSQL 和 SQLite 的 CREATE TABLE 语句 。 











































































































































































































































































































不 过 ， 这 种 方式 有 个 缺点 : 模型 的 Python 代码 可 能 与 数据 库 的 真正 结构 脱节 。 如 果 修 改 了 Django 模型 ， 还 
要 在 数据 库 中 做 相同 的 改动 ， 让 数据 库 与 模型 保持 一 致 。 本 章 后 面 讨 论 迁 移 (migration) 时 会 说 明 如 何 处 理 


这 个 问题 。 



































最 后 ， 要 知道 Django 提供 了 一 个 实用 程序 ， 可 以 内 省 现 有 的 数据 库 ， 生 成 模型 。 有 了 这 个 程序 ， 可 以 快速 让 
日 代码 运行 起 来 。 详 情 参见 第 21 章 。 
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4.4.1 第 一 个 模型 











为 了 给 本 章 和 下 一 章 提供 





个 连贯 的 示例 ， 我 将 实现 一 个 基本 的 “图 书 -作者 -出 版 社 "数据 布局 。 我 











之 所 以 以 


此 为 例 ， 是 因为 图 书 、 作 者 和 出 版 社 之 间 的 关系 是 大 家 熟知 的 ， 而 且 SQL 入 门 书 经 常 使 用 这 样 的 数据 布局 。 
你 现在 阅读 的 这 本 书 就 是 由 几 位 作者 撰写 ， 再 由 出 版 社 出 版 的 。 


下 面 对 一 些 概 念 、 字 段 和 关系 做 个 说 明 : 

















。 作者 有 名 字 、 姓 和 电子 邮件 地 址 。 
。 出 版 社 有 名 称 、 街 道 地 址 、 所 在 城市 、 州 (省 ) 、 国 家 和 网 站 。 








。 书 有 书 名 和 


版 日 



































期 ， 还 有 一 位 或 多 位 作者 (与 作者 是 多 对 多 关系 ) ， 以 及 一 个 出 版 社 【了 


键 ) 与 书 是 一 对 多 关系 ] 。 


8 版 社 (外 





在 Django 中 使 用 这 个 数据 库 布局 的 第 一 步 是 使 用 Python 代码 把 它 表示 出 来 。 在 startapp 命令 创建 的 mod- 
els.py 文件 中 输入 下 述 内 容 : 








from django.db import models 


class Publisher(models.Model): 

name = models.CharField(max_length=30) 

address = models.CharField(max_length=50) 

city = models.CharField(max_length=60) 

state_province = models.CharField(max_length=30) 
models.CharField(max_length=50) 
models.URLField() 


country = 
website = 


class Author(models.Model): 
first_name = models.CharField(max_length=30) 
Last_name = models.CharField(max_length=40) 
email = models.EmailField() 


class Book(models.Model): 
title = models.CharField(max_length=100) 
authors = models.ManyToManyField(Author) 


publisher = models.ForeignKey(Publisher) 
publication_date = models.DateField() 




















下 面 简单 说 明 这 上段 代码 ， 介 绍 一 些 基本 知识 。 首 先 ， 每 个 模型 使 用 一 个 Python 类 表示 ， 而 且 是 dj 
go.db.models.Model 的 子 类 。 父 类 Model 包含 与 数据 库 交 互 所 需 的 全 部 机 制 ， 而 且 只 让 模型 以 简洁 明了 的 句 


法 定义 字段 。 


你 可 能 不 信 ， 让 Django 


















































模型 中 的 各 个 属性 分 别 对 应 于 数据 库 表 中 的 一 列 。 属 性 的 名 称 对 应 于 列 的 名 称 ， 字 段 的 类 型 (如 
CharField) 对 应 于 数据 库 列 的 类 型 (如 varchar) 。 例 如 ，Publisher 模型 等 效 于 下 述 表 (假定 使 用 Post- 
greSQL 的 CREATE TABLE 句法 ) : 








CREATE TABLE "books_publisher" ( 
"id" serial NOT NULL PRIMARY KEY, 
"name" varchar(30) NOT NULL, 
"address" varchar(50) NOT NULL, 
"city" varchar(60) NOT NULL, 
"state_province" varchar(30) NOT NULL, 


an- 


具有 基本 的 数据 访问 能 力 只 需 编写 这 些 代码 。 一 般 ， 一 个 模型 对 应 于 一 个 数据 库 表 ， 
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"country" varchar(50) NOT NULL ， 
"website" varchar(200) NOT NULL 
) ; 








其 实 ， 稍 后 你 将 看 到 ，Django 能 自动 生成 CREATE TABLE 语句 。 一 个 类 对 应 一 个 数据 库 表 在 一 种 情况 下 有 全 
外 : 多 对 多 关系 。 在 上 述 示例 模型 中 ，Book 有 一 个 ManyToManyField 属性 ， 即 authors。 这 指明 一 本 书 有 一 位 
或 多 位 作者 ， 但 是 Book 数据 库 表 中 没有 authors 列 。 此 时 ，Django 会 创建 一 个 额外 的 表 ， 一 个 多 对 多 联结 

















(join table) ， 处 理 书 与 作者 之 间 的 对 应 关系 。 














完整 的 字段 类 型 和 模型 句法 选项 参见 附录 B。 最 后 请 注意 ， 我 们 没有 在 任何 一 个 模型 9 
































定义 主键 。 如 果 没 有 


明确 定义 ，Django 会 自动 为 每 个 模型 定义 一 个 自 增 量 整数 主键 字段 ， 名 为 td。 每 个 Django 模型 都 必须 有 一 

















个 主键 列 。 


4.4.2 安装 模型 





编写 好 代码 之 后 ， 要 在 数据 库 中 创建 表 。 为 此 ， 第 一 步 是 在 Django 项 目 中 激活 那些 模型 。 激 活 的 方法 是 把 
books 应 用 添加 到 设置 文件 中 “安装 的 应 用 ”列表 中 。 打 开 settings.py 文件 ， 找 到 INSTALLED_APPS 设置 。 它 的 















































作用 是 告诉 Django， 当 前 项 目 激 活 了 哪些 应 用 。 黑 认 情 况 下 ， 它 的 值 如 下 : 


INSTALLED APPS = ( 
"django.contrib.admin ' ， 
"django.contrib.auth ' ， 
"django.contrib.contenttypes ' ， 
"django.contrib.sesstons ' ， 
"django.contrib.messages ' ， 
'django.contrib.staticfiles', 


) 











为 了 注册 我 们 开发 的 “books” 应 用 ， 要 把 'books' ( 指 代 我 们 正在 开发 的 “books” 应 用 ) 添加 到 INSTALLED_APPS 














中 ， 得 到 下 述 设置 : 





INSTALLED APPS = ( 
'django.contrib.admin', 
"django.contrib.auth ' ， 
"django.contrib.contenttypes ' ， 
"django.contrib.sessions ' ， 
"django.contrib.messages ' ， 
'django.contrib.staticfiles', 
"books ' ， 


) 





























INSTALLED_APPS 中 的 各 个 应 用 通过 完整 的 Python 路 径 表 示 ， 即 点 分 包 路 径 ， 直 到 应 
































所 在 的 包 


。 在 设置 文件 











中 激活 Django 应 用 之 后 ， 可 以 在 数据 库 中 创建 表 了 。 首 先 ， 运 行 下 述 命令 ， 验 证 模型 : 








python manage.py check 


check 命令 运行 Django 系统 检查 框架 ， 即 验证 Django 项 目的 一 系列 静态 检查 。 如 果 一 切 正常 ， 
入 的 模型 代码 是 正太 














个 消息 : System check identified no issues (0 silenced)。 如 若 不 然 ， 请 确保 你 输 





























你 将 看 到 这 























的 。 错 误 消 息 应 该 会 告诉 你 代码 哪里 出 错 了 。 只 要 觉得 模型 有 问题 ， 就 可 以 运行 python manage.py check， 

















它 能 捕获 全 部 常见 的 模型 问题 。 








一 




















python manage.py makemigrations books 


角 认 模型 有 效 之 后 ， 运 行 下 述 命令 ， 告 诉 Django 你 对 模型 做 了 修改 〈 这 里 是 新 建 了 模型 ) : 
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你 应 该 会 看 到 类 似 下 面 的 输出 : 


Migrations for 'books': 
0Q001_initial.py: 
- Create model Author 
- Create model Book 
- Create model Publisher 
- Add field publisher to book 


Django 把 对 模型 (也 就 是 数据 库 模 式 ) 的 改动 存储 在 迁移 中 ， 迁 移 就 是 磁盘 中 的 文件 。 运 行 上 述 命令 后 ， 
books 应 用 的 migrations 文件 夹 里 会 出 现 一 个 名 为 90001_initial.py 的 文件 。migrate 命令 会 查看 最 新 的 迁移 
文件 ， 自 动 更 新 数据 库 模 式 ， 不 过 ， 我 们 先 来 看 看 将 运行 的 SQL。sqlmigrate 命令 的 参数 是 迁移 名 称 ， 输 出 
的 结果 是 对 应 的 SQL : 














python manage.py sqlmigrate books 0001 
你 应 该 看 到 类 似 下 面 的 输出 (为 了 便于 阅读 ， 重 新 做 了 排版 ): 


BEGIN; 


CREATE TABLE "books_author" (人 
"id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, 
"first_ name" varchar(30) NOT NULL, 
"last_name" varchar(40) NOT NULL, 
"email" varchar(254) NOT NULL 

); 

CREATE TABLE "books_book" ( 
"id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, 
"title" varchar(100) NOT NULL, 
"publication_ date" date NOT NULL 

); 

CREATE TABLE "books_ book authors" ( 
"id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, 
"book_id" integer NOT NULL REFERENCES "books_book" ("id"), 
"author_id" integer NOT NULL REFERENCES "books_author" ("id"), 
UNIQUE ("book_id", "author_id") 

); 

CREATE TABLE "books_publisher" ( 
"id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, 
"name" varchar(30) NOT NULL, 
"address" varchar(50) NOT NULL, 
"city" varchar(60) NOT NULL, 
"state_province" varchar(30) NOT NULL, 
"country" varchar(50) NOT NULL, 
"website" varchar(200) NOT NULL 

); 

CREATE TABLE "books_book__new" 
"id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, 
"title" varchar(100) NOT NULL, 
"publication date" date NOT NULL, 
"publisher_id" integer NOT NULL REFERENCES 
"books_publisher" ("id") 

); 
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INSERT INTO "books_book_ new" ("id", "publisher _ id", "title", 
"publication date") SELECT "id", NULL, "title", "publication_date" FROM 
"books_book"; 


DROP TABLE “books_ book"; 
ALTER TABLE "books_book__new" RENAME TO "books_book"; 
CREATE INDEX "books_book 2604cbea" ON "books_ book" ("publisher_id"); 
COMMIT; 
注意 以 下 几 点 : 


。 自动 生成 的 表 名 结合 应 用 的 名 称 (books) 和 模型 名 的 小 写 形式 (publisher、book 和 author) 。 这 个 
行为 可 以 覆盖 ， 详 情 参 阅 附 录 B。 


。 前 面 说 过 ，Django 会 自动 为 各 个 表 添 加 主键 ， 即 id 字段 。 这 个 行为 可 以 覆盖 。 按 约定 ，Dijango 在 外 
键 字段 的 名 称 后 面 加 上 "_id"。 你 可 能 猜 到 了 ， 这 个 行为 也 可 以 覆盖 。 
。 外 键 关 系 通过 REFERENCES 语句 指明 。 
































CREATE TABLE 语句 会 针对 所 用 的 数据 库 调整 ， 因 此 能 自动 处 理 数据 库 专 有 的 字段 类 型 ， 例 如 auto_incre- 
ment (MySQL) 、serial (PostgreSQL) 或 integer primary key (SQLite) 。 列 名 的 引号 也 是 如 此 (例如 使 
用 双 引 号 或 单 引号 ) 。 上 述 示例 输出 用 的 是 PostgreSQL 句法 。 


sqlmigrate 命令 并 不 创建 表 ， 其 实 它 根本 不 接触 数据 库 ， 而 是 在 屏幕 上 输出 Django 将 执行 的 SQL。 如 果 愿 
意 ， 可 以 把 输出 的 SQL 复制 粘贴 到 数据 库 客户 端 里 ， 然 而 ，Django 为 提交 SQL 提供 了 更 为 简单 的 方式 


一 一 migrate 命令 : 

































































python manage.py migrate 


运行 这 个 命令 后 将 看 到 类 似 下 面 的 输出 : 














Operations to perform: 

Apply all migrations: books 
Running migrations: 

Rendering model states... DONE 


Applying books.0001 initial... OK 


# ... 




















那些 额外 的 输出 (注释 掉 的 部 分 ) 是 首次 运行 迁移 时 Django 创建 的 系统 表 ， 是 Django 内 置 应 用 所 需 的 。 迁 
移 是 Django 把 模型 改动 〈 添 加 字段 、 删 除 模型 ， 等 等 ) 应 用 到 数据 库 模 式 的 方式 。 大 多 数 情 况 下， 迁移 能 自 
动 完 成 工作 ， 然 而 也 有 一 些 不 足 。 关 于 迁移 的 更 多 信息 ， 参 阅 第 21 章 。 
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创建 模型 之 后 ，Django 自动 提供 了 操作 模型 的 高 层 Python API。 运 行 python manage.py sheLL， 输 入 下 述 代 
码 试 试 : 
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>>> from books.models import Publisher 

>>> p1 = Publisher(name='Apress', address='2855 Telegraph Avenue', 
city='Berkeley', state_province='CA', country='U.S.A.', 
website='http://www.apress.com/') 

>>> p1.save() 

>>> p2 = Publisher(name="0'Reilly", address='10 Fawcett St.', 
city='Cambridge', state province='MA', country='U.S.A.', 
website='http://www.oreilly.com/') 

>>> p2.save() 

>>> publisher_list = Publisher.objects.all() 

>>> publisher_list 

[<Publisher: Publisher object>, <Publisher: Publisher object>] 














这 么 几 行 代码 完成 的 工作 很 多 。 下 面 着 重 说 明 几 点 : 











。 首先 ， 导 入 Publisher 模型 类 ， 以 便 与 保存 出 版 社 的 数据 库 表 交互 。 
。 提供 各 个 字段 的 值 ，name、address， 等 等 ， 实 例 化 一 个 Publisher 对 象 。 
。 为 了 把 对 象 保存 到 数据 库 中 ， 调 用 save() 方法 。Django 在 背后 执行 SQL INSERT 语句 。 


。 为 了 从 数据 库 中 检索 出 版 社 ， 使 用 Publisher .objects 属性 ， 你 可 以 把 它 的 值 理解 为 全 部 出 版 社 。 使 
用 Publisher .objects.all() 获取 数据 库 中 的 所 有 Publisher 对 象 。Django 在 背后 执行 SQL SELECT 语 
句 。 


















































有 一 件 事 在 上 述 示例 中 可 能 没有 明确 体现 出 来 ， 要 提 一 下 。 使 用 Django 模型 API 创建 的 对 象 不 会 自动 保 
存 ， 只 能 自己 动手 调用 save() 方法 : 






































p1 = Publisher(...) 

# 此 时 ，pl 尚未 保存 到 数据 库 中 1 
p1.save() 

# 现在 保存 了 。 


如 果 想 在 一 步 中 创建 对 象 并 保存 到 数据 库 中 ， 使 用 objects.create() 方法 。 下 述 示例 与 前 述 示例 等 效 : 





























>>> pl1 = Publisher .objects.create(name='Apress ' ， 
address='2855 TeLegraph Avenue ' ， 
city='Berkeley', state province='CA', country='U.S.A.', 
website='http://www.apress.com/') 

>>> p2 = Publisher.objects.create(name="0'Reilly", 
address='10 Fawcett St.', city='Cambridge', 
state_province='MA', country='U.S.A.', 
website='http://www.oreilly.com/') 

>>> publisher_list = Publisher.objects.all() 

>>> publisher_list 

[<Publisher: Publisher object>, <Publisher: Publisher object>] 




















当然 ， 使 用 Django 数据 库 API 能 执行 相当 多 的 操作 ， 不 过 我 们 先 来 处 理 一 件 让 人 烦恼 的 小 事 。 


4.5.1 添加 模型 的 字符 串 表 示 形 式 
打印 出 版 社 列表 时 ， 得 到 的 是 下 述 没 有 什么 用 的 输出 ， 不 易 区 分 各 个 Publisher 对 象 : 


[<Publisher: Publisher object>, <Publisher: Publisher object>] 
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这 个 问题 易于 修正 ， 为 Publisher 类 添加 一 个 名 为 _str_() 的 方法 即 可 。__str_() 方法 的 作用 是 告诉 
Python 如 何以 人 类 可 读 的 形式 显示 对 象 。 我 们 为 那 三 个 模型 添加 _str_() 方法 ， 看 看 效果 : 

















from django.db import models 


class Publisher(models.Model): 
name = models.CharField(max_length=30) 
address = models.CharField(max_length=50) 
city = modeLs.CharFieLd(max_Length=60) 
state_province = models.CharField(max_length=30) 
country = models.CharField(max_length=50) 
website = models.URLField() 


def _str_ (self): 
return self.name 


class Author(models.Model): 
first_name = models.CharField(max_length=30) 
Last_name = models.CharField(max_length=40) 
email = models.EmailField() 


def _str_(self): 
return u'%s %s' % (self.first name, self.last name) 


class Book(models.Model): 
title = models.CharField(max_length=100) 
authors = models.ManyToManyField(Author) 
publisher = models.ForeignKey(Publisher) 
publication_date = models.DateField() 


def _ str_(self): 
return self.title 


可 以 看 出 ， 为 了 返回 对 象 的 表示 形式 ，__str__() 方法 可 以 做 任何 需要 做 的 事情 。 这 里 ，Publisher 和 Book 类 
的 _str_() 方法 只 是 分 别 返 回 对 象 的 名 称 和 标题 ， 而 Author 类 的 _str__() 方法 稍微 复杂 一 些 ， 把 
first_name 和 Last_name 字段 放 在 一 起 ， 以 一 个 空格 分 开 。 对 __str_() 方法 的 唯一 要 求 是 返回 一 个 字符 串 
对 象 。 如 若 不 然 ， 而 是 返回 整数 ，Python 会 抛 出 TypeError 异常 ， 显 示 下 述 消息 : 




















TypeError: __str__ returned non-string (type int). 

















为 了 让 增加 的 _str__() 方法 起 作用 ， 退 出 Python shell， 再 运行 python manage.py shell 命令 进入 。 (这 是 
让 代码 改动 起 作用 的 最 简单 方式 。) 现在 ，Publisher 对 象 列 表 容 易 理解 多 了 : 











>>> from books.models import Publisher 

>>> publisher_list = Publisher.objects.all() 
>>> publisher_list 

[<Publisher: Apress>, <Publisher: O'Reilly>] 


每 个 模型 都 应 该 定义 _str_() 方法 ， 这 样 做 不 仅 是 为 了 你 自己 在 使 用 交互 式 解释 器 时 提供 便利 ， 还 因为 
Django 在 显示 对 象 的 多 个 地 方 需要 用 到 _str__() 方法 的 输出 。 最 后 注意 一 点 ，__str_() 是 为 模型 添加 行 > 
的 好 例子 。Django 模型 不 仅仅 用 于 描述 对 象 的 数据 库 表 布 局 ， 还 用 于 描述 对 象 知道 如 何 处 理 的 功能 。 

一 str_() 就 是 其 中 一 例 ， 其 作用 是 让 模型 知道 如 何 显示 自身 。 
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4.5.2 插入 和 更 新 数据 


我 们 已 经 见 过 如 何在 数据 库 中 插入 一 行 ， 先 使 用 关键 字 参 数 创 建 模型 的 实例 ， 如 下 所 示 : 





>>> p = Publisher(name='Apress', 
address='2855 Telegraph Ave.', 
city='Berkeley', 
state_province='CA', 
eoUuNtry= USA , 
website='http://www.apress.com/') 





前 面 说 过 ， 实 例 化 模型 类 不 会 接触 数据 库 。 为 了 把 记录 保存 到 数据 库 中 ， 要 像 下 面 这 样 调用 save() 方法 : 
>>> p.save() 
这 一 步 基本 上 相当 于 下 述 SQL 语句 : 


INSERT INTO books_publisher 
(name, address, city, state province, country, website) 
VALUES 
('Apress', '2855 Telegraph Ave.', 'Berkeley', 'CA', 
'U.S.A.', 'http://www.apress.com/'); 


Publisher 模型 有 个 自 增 量 主键 id， 因 此 调用 save( ) 方法 后 还 会 做 一 件 事 : 计算 记录 的 主键 值 ， 把 它 赋值 给 
实例 的 id 属性 。 

















>>> p.id 
52 # 你 得 到 的 结果 可 能 不 同 











后 续 再 调用 save() 将 就 地 保存 记录 ， 而 不 新 建 记录 ( 即 ， 执 行 SQL UPDATE 语句 ， 而 非 INSERT 语句 ) : 











>>> p.name = 'Apress Publishing' 
>>> p.save() 





上 述 save() 调用 基本 上 相当 于 执行 下 述 SQL 语句 : 


UPDATE books_publisher SET 
name = 'Apress Publishing', 
address = '2855 Telegraph Ave.', 
city = 'Berkeley', 
state_province = 'CA', 
GOUntFy = 册 SA ', 
website = 'http://www.apress.com' 
WHERE id = 52; 








是 的 ， 注 意 所 有 字段 都 将 更 新 ， 而 不 是 只 更 新 有 变化 的 字段 。 这 在 某 些 逻辑 中 可 能 导致 条 件 竞争 。 执 行 下 述 
查询 ( 稍 有 不 同 ) 的 方法 参见 4.5.9 市 : 


UPDATE books_publisher SET 


name = 'Apress Publishing' 
WHERE id=52; 


4.5.3 选择 对 象 


知道 如 何 创建 和 更 新 数据 库 记 录 是 基本 的 ， 但 是 你 构建 的 Web 应 用 程序 可 能 更 多 的 是 查询 现 有 对 象 ， 而 非 新 
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建 。 我 们 已 经 见 过 检索 指定 模型 中 每 个 记录 的 一 种 方式 : 





>>> Publisher .objects.all() 
[<Publisher: Apress>, <Publisher: O'Reilly>] 





这 基本 上 相当 于 下 述 SQL 语句 : 


SELECT id, name, address, city, state _ province, country, website 
FROM books_publisher; 


注意 ， 查 找 数据 时 ，Django 使 用 的 不 是 SELECT *， 而 是 把 所 有 字段 列 出 来 。 这 样 做 是 有 原因 
的 : 某 些 情况 下 ，SELECT * 较 慢 ,而 (更 重要 的 是 ) 列 出 字段 更 接近 “Zen of Python” (Python 
之 禅 ) 中 的 一 个 原则 一 一 “Explicit is petter than implicit”( 明 了 胜 于 星 深 ) 。 如 果 想 查看 Python 
之 禅 的 更 多 内 容 ， 在 Python 提示 符 中 输入 import this。 














下 面 详细 分 析 Publisher .objects.all() 这 行 代 码 : 


。 首先 ，Publisher 是 我 们 定义 的 模型 。 这 没什么 可 意外 的 ， 想 查找 数据 就 应 该 使 用 相应 的 模型 。 

。 然后 ,访问 objects 属性 。 这 叫 管理 器 (manager) ， 在 第 9 章 详 述 。 现 在 ， 你 只 需 知道 ， 管 理 器 负责 
所 有 “表层 ”数据 操作 ， 包 括 (最 重要 的 ) 数据 查询 。 所 有 模型 都 自动 获得 一 个 objects 管理 器 ， 需 要 
查询 模型 实例 时 都 要 使 用 它 。 

。 最 后 ， 调 用 aLL() 方法 。 这 是 objects 管理 器 的 一 个 方法 ， 返 回 数据 库 中 的 所 有 行 。 虽 然 返 回 的 对 象 
看 似 一 个 列表 ,但 其 实 是 一 个 查询 集合 (QuerySet) 一 一 表示 数据 库 中 一 系列 行 的 对 象 。 附 录 C 将 详 
细 说 明 查 询 集 合 。 本 章 都 将 把 它 视 作 它 所 模仿 的 列表 。 











所 有 数据 库 查 找 操作 都 遵守 这 种 一 般 模 式 ， 即 在 依附 于 模型 的 管理 器 上 调用 方法 ， 执 行 相应 的 查询 。 


4.5.4 过 滤 数 据 
当然 ， 我 们 很 少 需要 一 次 性 从 数据 库 中 选择 所 有 数据 。 多 数 情 况 下 ， 我 们 只 想 处 理 数据 的 子 集 。 在 Django 
API 中 ， 可 以 使 用 filter() 方法 过 滤 数 据 : 


>>> PubLisher.objects.fLLter(name='Apress ') 
[<Publisher: Apress>] 


filter() 的 关键 字 参 数 转换 成 相应 的 SQL WHERE 子 句 。 上 述 示例 得 到 的 SQL 语句 如 下 : 


SELECT id, name, address, city, state province, country, website 
FROM books_publisher 
WHERE name = 'Apress'; 


可 以 把 多 个 参数 传 给 filter() 方法 ， 进 一 步 收 窗 要 查询 的 数据 : 


>>> Publisher .objects.filter(country="U.S.A.", 
state_province="CA") 
[<Publisher: Apress>] 


多 个 参数 转换 成 SQL AND 子 句 。 因 此 ， 上 述 示 例 中 的 代码 片段 得 到 的 SQL 语句 如 下 : 


SELECT id, name, address, city, state province, country, website 
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FROM books_publisher 
WHERE country = 'U.S.A.' 
AND state_province = 'CA'; 





注意 ， 查 找 操 作 默认 使 用 SQL = 运算 符 做 精确 匹配 查找 。 其 他 查找 类 型 还 有 : 


>>> Publisher .objects.filter(name__contains="press") 
[<Publisher: Apress>] 














注意 ，name 和 contaiins 之 间 有 两 个 下 划 线 。 与 Python 一 样 ，Django 使 用 双 下 划 线 表示 “魔法 ”操作 。 这 里 ， 
Django 把 _contains 部 分 转换 成 SQL LIKE 语句 : 











SELECT id, name, address, city, state province, country, website 
FROM books_publisher 
WHERE name LIKE '%press%'; 





支持 的 其 他 查找 类 型 有 : icontains (不 区 分 大 小 写 的 LIKE) ，startswith 和 endswith， 以 及 range (SQL 
BETNEEN 语句 ) 。 附 录 B 详细 说 明 这 些 查找 类 型 。 


























4.5.5 检索 单个 对 象 
上 述 fiLter() 示例 都 返回 一 个 查询 集合 (可 视 作 列表 ) 。 有 时 ， 较 之 列表 ， 更 适合 获取 单个 对 象 。 此 时 应 该 
使 用 get() 方 法: 


>>> Publisher .objects.get(name="Apress") 
<Publisher: Apress> 














方法 只 返回 一 个 对 象 ， 而 不 是 一 个 列表 (更 确切 地 说 是 查询 集合 ) 。 因 此 ， 得 到 多 个 对 象 的 查询 会 导致 


类 洗 
笠 人 





>>> Publisher .objects.get(country="U.S.A.") 
Traceback (most recent call last): 


MultipleObjectsReturned: get() returned more than one Publisher -- it returned 2! Loo\ 
kup parameters were {'country': 'U.S.A.'} 


不 返回 对 象 的 查询 也 导致 异常 : 


>>> Publisher .objects.get(name="Penguin") 
Traceback (most recent call last): 


DoesNotExist: Publisher matching query does not exist. 

















DoesNotExist 异常 是 模型 类 的 属性 一 一 Publisher .DoesNotExist。 在 应 用 程序 中 可 以 像 下 症 


入 


于 


这 样 捕获 这 个 


并 


try: 

p = Publisher.objects.get(name='Apress') 
except Publisher .DoesNotExist: 

print ("Apress isn't in the database yet.") 
else: 

print ("Apress is in the database.") 
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4.5.6 排序 数据 


在 运行 上 述 示例 的 过 程 中 你 可 能 发 现 了 ， 返 回 的 对 象 好 像 是 随机 排序 的 。 你 想 的 没 错 ， 目 前 我 们 没有 告诉 数 
据 库 如 何 排序 结果 ， 因 此 数据 使 用 数据 库 选 择 的 顺序 排序 。 在 Django 应 用 程序 中 ， 你 可 能 想 根据 特定 值 排序 
结果 ， 例 如 按 字母 表 顺 序 。 为 此 ， 使 用 order_by() 方法 : 























>>> Publisher .objects.order_by("name") 
[<Publisher: Apress>, <Publisher: O'Reilly>] 


结果 好 像 与 之 前 的 aLL() 示例 没有 什么 区 别 ， 不 过 现在 SQL 中 指定 了 顺序 : 


SELECT id, name, address, city, state province, country, website 
FROM books_publisher 
ORDER BY name ; 


可 以 根据 任何 字段 排序 : 


>>> Publisher .objects.order_by("address") 
[<Publisher: O'Reilly>, <Publisher: Apress>] 


>>> Publisher .objects.order_by("state province") 
[<Publisher: Apress>, <Publisher: O'Reilly>] 





如 果 想 根据 多 个 字段 排序 (以 第 一 个 字段 排 不 出 顺序 时 使 用 第 二 个 字段 ) ， 提 供 多 个 参数 : 


>>> Publisher .objects.order_by("state_province", "address") 
[<Publisher: Apress>, <Publisher: O'Reilly>] 








此 外 ， 还 可 以 反 向 排序 。 方 法 是 在 字段 名 称 前 面 加 上 “-”( 减 号 ) : 


>>> Publisher .objects.order_by("-name") 
[<Publisher: O'Reilly>, <Publisher: Apress>] 


虽然 order_by() 有 一 定 的 灵活 性 ， 但 是 每 次 都 调用 它 相 当 繁 玉 。 多 数 时候 ， 我 们 始终 使 用 同一 个 字段 排序 。 
此 时 ， 可 以 在 模型 中 指定 默认 排序 : 








class Publisher(models.Model): 
name = models.CharField(max_length=30) 
address = models.CharField(max_length=50) 
city = models.CharField(max_length=60) 
state_province = models.CharField(max_length=30) 
country = models.CharField(max_length=50) 
website = models.URLField() 


def _ str__(self): 
return seLf.name 


class Meta: 
ordering = ['name'] 





这 里 出 现 了 一 个 新 概念 ， 内 极 在 Publisher 类 定义 体 中 的 class Meta ( 即 要 缩 进 ， 放 在 class Publisher 内 
部 ) 。 任 何 模型 都 可 以 使 用 Meta 类 指定 多 个 针对 所 在 模型 的 选项 。 全 部 可 用 的 选项 参见 附录 B ， 现 在 我 们 关 
注 的 是 排序 选项 。 指 定 这 个 选项 后 ， 使 用 Django 数据 库 API 检索 Publisher 对 象 时 ， 如 果 没 有 明确 调用 or- 
der_by()， 都 按照 name 字段 排序 。 
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4.5.7 链 式 查找 


我 们 知道 如 何 过 滤 数据 ， 也 知道 如 何 排序 数据 了 。 当 然 ， 这 两 个 操作 经 常 需 要 一 起 做 。 此 时 ， 可 以 把 查找 “ 链 


接 ” 在 一 起 : 


>>> Publisher .objects.filter(country="U.S.A.").order_by("-name") 
[<Publisher: O'Reilly>, <Publisher: Apress>] 


正如 你 所 期 待 的 那样 ， 得 到 的 SQL 查询 中 既 有 WHERE 子 句 ， 也 有 ORDER BY 子 句 : 


SELECT id, name, address, city, state province, country, website 
FROM books_publisher 

WHERE country = 'U.S.A' 

ORDER BY name DESC; 


4.5.8 切片 数据 

















另 一 个 常见 的 需求 是 只 查找 固定 数量 的 行 。 假 如 数据 库 中 有 几 千 个 出 版 社 记 录 ， 但 是 只 想 显 示 第 一 





此 ， 可 以 使 用 Python 标准 的 列表 切片 句法 : 


>>> Publisher .objects.order_by('name' )[0] 
<Publisher: Apress> 





得 到 的 SQL 语句 基本 如 下 : 


SELECT id, name, address, city, state province, country, website 
FROM books_publisher 

ORDER BY name 

LIMIT 1» 


类 似 地 ， 可 以 使 用 Python 的 范围 切片 句法 检索 数据 子 集 : 


>>> Publisher .objects.order_by('name' )[0:2] 





这 样 得 到 的 是 两 个 对 象 ， 基 本 上 相当 于 下 述 SQL 语句 : 


SELECT id, name, address, city, state province, country, website 
FROM books_publisher 

ORDER BY name 

OFFSET © LIMIT 2: 


注意 ， 不 支持 使 用 负数 : 


>>> Publisher .objects.order_by('name')[-1] 
Traceback (most recent call last): 


AssertionError: Negative indexing is not supported . 


不 过 ， 这 容易 解决 。 只 需 修改 order_by() 语句 ， 如 下 所 示 : 





>>> Publisher .objects.order_by('-name' )[0] 


4.5.9 在 一 个 语句 中 更 新 多 个 对 象 











a 为 


4.5.2 节 说 过 ，save() 方法 更 新 一 行 中 的 所 有 列 。 然 而 ， 你 的 应 用 程序 可 能 只 需要 更 新 部 分 列 。 比 如 说 ， 你 可 
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能 想 把 Apress 出 版 社 的 名 称 由 'Apress' 改 为 'Apress PubLishing' 。 使 用 save() 的 代码 如 下 : 


>>> p = PubLisher.objects.get(name='Apress ' ) 
>>> p.name = 'Apress Publishing' 
>>> p.save() 





这 基本 上 相当 于 下 述 SQL 语句 ， 


SELECT id, name, address, city, state province, country, website 
FROM books_publisher 
WHERE name = 'Apress'; 


UPDATE books_publisher SET 
name = 'Apress Publishing', 
address = '2855 Telegraph Ave.', 
city = 'Berkeley', 
state_province = 'CA', 
GOUntPy := "WS A "; 
website = 'http://www.apress.com' 
WHERE id = 





(注意 ， 这 个 示例 假定 Apress 的 ID 为 52。) 从 这 个 示例 可 以 看 出 ，Django 的 save() 方法 会 设 定 所 有 列 的 
值 ， 而 不 是 只 设 定 name 列 的 值 。 如 果 你 所 处 的 环境 可 能 同时 由 其 他 操作 修改 其 他 列 ， 最 好 只 更 新 需要 修改 的 
值 。 为 此 ， 使 用 QuerySet 对 象 的 update() 方法 。 例如: 














>>> Publisher .objects.filter(id=52).update(name='Apress Publishing') 
这 样 得 到 的 SQL 语句 更 高 效 ， 而 且 不 会 导致 条 件 竞争 : 


UPDATE books_publisher 
SET name = 'Apress PubLishing' 
WHERE id = 





update() 方法 可 以 在 任何 QuerySet 对 和 象 上 调用 ， 这 意味 着 可 以 通过 它 批 量 编辑 多 个 记录 。 下 述 代码 把 每 个 
Publisher 记录 的 country 列 都 由 'U.S.A.' 改 为 'USA': 














>>> Publisher .objects.all().update(country='USA') 
医 


update() 方法 有 返回 值 ， 是 一 个 整数 ， 表 示 修 改 的 记录 数量 。 在 上 述 示例 中 ， 返 回 值 是 2。 


4.5.10 删除 对 象 

















若 想 从 数据 库 中 删除 一 个 对 象 ， 只 需 在 对 象 上 调用 delete() 方法 : 





>>> p = Publisher.objects.get(name="0'Reilly") 
>>> p.delete() 

>>> Publisher .objects.all() 

[<Publisher: Apress Publishing>] 














此 外 ， 还 可 以 在 任何 QuerySet 对 象 上 调用 delete() 方法 ， 批 量 删除 对 象 。 这 与 前 一 节 所 讲 的 update() 方法 
类 似 。 











>>> Publisher .objects.filter(country='USA').delete() 
>>> Publisher .objects.all().delete() 
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>>> Publisher .objects.all() 
[] 


删除 数据 要 谨慎 ! 为 了 防止 不 小 心 把 表 中 的 数据 都 删除 ， 想 删除 表 中 的 一 切 数据 时 ，Django 要 求 必须 显 式 调 
用 att() 方法 。 例 如 ， 下 述 代码 无 效 : 








>>> Publisher .objects.delete() 
Traceback (most recent call last): 
File "", line 1, in 
AttributeError: 'Manager' object has no attribute 'delete' 


添加 alLL() 方法 后 就 可 以 了 : 


>>> Publisher .objects.all().delete() 








如 果 只 想 删 除 部 分 数据 ， 无 需 调 用 aLL() 方法 。 下 面 再 以 前 面 的 一 个 示例 为 例 : 











>>> Publisher .objects.filter(country='USA').delete() 


4.6 接 下 来 





读 完 本 章 后 ， 你 掌握 了 足够 的 Django 模型 知识 ， 可 以 编写 基本 的 数据 库 应 用 程序 了 。 第 9 章 将 说 明 Django 
数据 库 层 的 一 些 高 级 用 法 。 定 义 好 模型 之 后 ， 接 下 来 应 该 使 用 数据 填充 数据 库 。 你 可 能 有 旧 数据 ， 此 时 可 以 
阅读 第 21 章 ， 了 解 如 何 集成 旧 数 据 库 。 你 可 能 依靠 网 站 的 用 户 提供 数据 ， 此 时 可 以 阅读 第 6 章 ， 学 习 如 何 处 
理 用 户 提交 的 表单 数据 。 但 是 ， 有 些 情况 下 ， 你 或 者 你 所 在 的 团队 要 自己 动手 录入 数据 ， 此 时 最 好 有 一 个 
Web 界面 ， 用 于 输入 和 管理 数据 。 下 一 章 介 绍 的 Django 管理 界面 正 是 为 这 种 情况 而 生 的 。 
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第 5 章 Django 管理 后 台 




















对 多 数 现代 的 网 站 而 言 ， 管 理 界 面 是 基础 设施 的 重要 组 成 部 分 。 这 是 一 个 Web 界面 ， 限 制 只 让 授信 的 网 站 管 
理 员 访问 ， 用 于 添加 、 编 辑 和 删除 网 站 内 容 。 常 见 的 示例 有 : 发 布 博客 的 界面 ， 网 站 管理 人 员 审 核 用 户 评 论 
的 后 端 ， 客 户 用 来 更 新 新 闻 稿 的 工具 。 


不 过 ， 管 理 界面 有 个 问题 : 构建 起 来 繁琐 。 构 建 面向 公众 的 功能 时 ，Web 开发 是 有 趣 的 ， 但 是 管理 界面 一 成 
不 变 ， 要 验证 用 户 身份 、 显 示 并 处 理 表单 、 验 证 输入 ， 等 等 。 这 个 过 程 无 趣 、 乏 味 。 


那么 ， 对 这 样 一 个 无 趣 、 乏 味 的 任务 ，Django 采取 了 什么 措施 呢 ? 它 为 你 代劳 了 。 


在 Django 中 ， 构 建 管理 界面 不 算 个 事 。 本 章 探讨 Django 自动 生成 的 管理 界面 ， 了 解 它 为 模型 提供 的 便利 界 
面 ， 以 及 可 以 使 用 的 其 他 功能 。 







































































5.1 使 用 Django 管理 后 台 


在 第 1 章 中 运行 django-admin startproject mysite 时 ，Django 为 我 们 创建 并 配置 了 默认 的 管理 后 台 。 我 们 
只 需 创 建 一 个 管理 员 用 户 (超级 用 户 ) ， 就 可 以 登录 管理 后 台 。 


| 


如 果 你 使 用 Visual Studio， 无 需 在 命令 行 中 完成 接 下 来 的 步 又， 在 Visual Studio 的 “项 目 * 菜 单 
中 添加 一 个 超级 用 户 即 可 。 















































执行 下 述 命令 ， 创 建 一 个 管理 员 用 户 : 





python manage.py createsuperuser 
输入 想 用 的 用 户 名 ， 然 后 按 回 车 键 ， 
Username: admin 
接 下 来 会 提示 你 输入 电子 邮件 地 址 : 
Email address: admin@example.com 


最 后 ， 输 入 密码 。 密 码 要 输入 两 次 ， 第 二 次 是 对 第 一 次 的 确认 。 








PasSWOord : 天光 炎炎 炎炎 炎炎 天 炎 
Password (again) : ***w*w***** 


Superuser created successfully. 


5.1.1 启动 开发 服务 器 


在 Django 1.8 中 ， 管 理 后 台 默 认 已 激活 。 下 面 启动 开发 服务 器 ， 用 一 下 它 。 读 过 前 面 几 章 我 们 知道 ， 启 动 开 
发 服务 器 的 方法 如 下 : 








67 


python manage.py runserver 


现在 ， 打 开 Web 浏览 器 ,访问 本 地 域名 上 的 /admin/ 路 径 ， 例 如 http://127.0.0.1:8000/admin/。 你 应 该 看 
到 管理 后 台 的 登录 界面 (图 5-1) 。 


口 Log in | Django site admin Xx 


所 GL 省 | 口 127.0.0.1:8000/admin/login/?next=/admin/ ye O N 习 三 


Username: 
| 


Password: 











Log in 


图 5-1，Django 管理 后 台 的 登录 界面 




















因为 默认 启用 了 本 地 化 ， 所 以 登录 界面 可 能 会 使 用 你 所 选 的 语言 显示 ， 当 然 ， 这 取决 于 浏览 器 的 设置 和 
Django 是 否 有 那 门 语言 的 翻译 。 





5.1.2 进入 管理 后 台 


























现在 ， 使 用 前 面 创建 的 超级 用 户 账户 登录 。 登 录 后 应 该 看 到 Django 管理 后 台 的 首页 (图 5-2) 。 











你 应 该 看 到 两 种 可 编辑 的 内 容 : Groups (分 组 ) 和 Users (用 户 ) 。 这 是 Django 自 带 的 身份 验证 框架 djan- 
go.contrib.auth 提供 的 。 管 理 后 台 主 要 供 非 技术 人 员 使 用 ， 因 此 无 需 过 多 解释 。 尽 管 如 此 ， 我 们 还 是 要 快速 
介绍 一 些 基本 功能 。 























68 - 第 5 章 Django 管理 后 台 


口 Site administration | Dian”X 


€ CC 省 | 间 127.0.0.1:8000/admin/ F909 OO 日 一 


Welcome, admin. View site / Change password / Log out 


Site administration 





。 Recent Actions 
roups 中 Add gChange My Actions 
Users 中 Add Change None available 
上 


5-2，Django 管理 后 台 的 首页 


Django 中 每 种 数据 都 有 一 个 修改 列表 和 编辑 表单 。 前 者 列 出 数据 库 中 所 有 可 用 的 对 象 ， 后 者 用 于 添加 、 修 改 
或 删除 数据 库 中 的 特定 记录 。 点 击 “Users” 那 一 行 里 的 “Change” 链 接 ， 加 载 用 户 的 修改 列表 (图 5-3) 。 


一 口 Xx 
口 Select userto change ID x 有 有 汪汪 


€ G 省 | 人 127.0.0.1:8000/admin/auth/user/ woO [N 引 三 


Welcome, admin. View site / Change password / Log out 


Home » Authentication and Authorization » Users 








Select user to change 
Q [ | Search i 
By staff status 
All 
Action:  --------- v | Go | 0of 1] selected Yes 
No 
Username a Emailaddress Firstname lastname Staff status 
admin nigel@masteringdjango.com © By superuser status 
All 
1 user Yes 
No 
By active 
All 
Yes 
No 


只 


图 5-3， 用 户 的 修改 列表 页 面 


这 个 页 面 显示 数据 库 中 的 所 有 用 户 ， 你 可 以 把 它 想 象 成 SQL 查询 SELECT * FROM auth_user; 的 精美 Web 版 
本 。 如 果 你 一 直 跟 着 书 中 的 示例 做 ， 会 看 到 一 个 用 户 ; 添加 更 多 的 用 户 后 ， 你 会 发 现 过 滤 、 排 序 和 搜索 功能 
很 有 用 。 

















过 滤 功 能 在 右边 ， 排 序 通过 点 击 表 关 实现， 搜索 框 在 项 部， 可 以 通过 用 户 名 搜索 。 点 击 用 户 的 用 户 名 后 会 看 
到 编辑 用 户 的 表单 (图 5-4) 。 
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口 Change user| Django site x WN 
€ @G 省 | DD 127.0.0.1:8000/admin/auth/user/1 


Home ; Authentcabon and Authorization » Users » ad 


安 O 〇 四 三 


Welcome, admin. View site / Change password / Log out = 


Change user [ History ) 
Username: adman 
algorithm Pbkdf2 sha256 iterations: 20000 salt: h7AwXP hash 
Password KINART Passes A fess 
有 4 thr 
NR form 
First name 
Last name 
mgelipmasteningdjango.com 


Email address 


图 5-4， 编 辑 用 户 的 表单 


在 这 个 页 面 中 可 以 修改 用 户 的 属性 ， 侈 如 姓名 和 各 种 权限 。 注 意 ， 如 果 想 修改 用 户 的 密码 ， 点 击 密码 字段 下 








面 的 链接 ， 不 能 直接 修改 哈 希 密码 。 

















还 要 注意 ， 不 同 字段 类 型 显示 的 小 组 件 不 同 ， 例 如 ， 日 期 (时 间 ) 字段 显示 的 是 日 历 控件 、 布 尔 值 字段 显示 





















































的 是 复 选 枉 、 字 符 字段 显示 的 是 文本 输入 框 。 
如 果 想 删除 记录 ， 点 击 编辑 表单 左下 角 的 "Delete "按钮 。 点 击 那 个 按钮 后 会 显示 确认 页 面 ， 有 时 那个 页 面 还 会 
显示 要 删除 的 依赖 对 象 。 (比如 说 删除 出 版 社 记录 时 ， 那 个 出 版 社 名 下 的 图 书 也 将 被 删除 ! ) 
































如 果 想 添加 记录 ， 在 管理 后 台 首 页 点 击 相应 行 里 的 “Add” 链 接 。 此 时 显示 一 个 空 表 单 ， 让 你 填写 数据 。 














注意 ， 管 理 界面 还 能 验证 输入 。 留 空 必 填 的 字段 ， 或 者 在 日 期 字段 中 输入 无 效 的 日 期 试 坛 ， 保 存 时 会 看 到 类 





及 


似 < 








5-5 中 的 错误 。 











编辑 现 有 对 象 时 ， 窗 口 右上 角 有 个 “History" 链 接 。 通 过 管理 界 





链接 便 可 查看 (图 5-6) 。 


i 所 做 的 每 个 改动 都 记录 在 案 ， 点 击 “History” 

















管理 后 台 在 背后 是 如 何 工 作 的 呢 ? 相当 简单 。 启 动 服 务 器 时 ，Django 运行 admin.autodiscover() 也 


台 的 运作 方式 











文件 ， 就 执行 里 面 的 代码 。 在 books 应 





























其 实 ，Django 管理 后 台 也 是 一 个 Django 应 用 程序 ， 有 
之 所 以 有 管理 后 台 ， 是 因为 你 在 URL 配置 中 设置 了 


在 早期 的 Django 版 本 中 ， 要 在 urls.py 文件 中 调用 这 个 函数 ， 但 是 现实 Django 会 自动 运行 它 。 这 个 函 
数 迭 代 INSTALLED_APPS 设置 ， 在 安装 的 各 个 应 用 中 查找 一 个 名 为 admin.py 的 文件 。 如 果 应 用 中 存在 这 个 
用 的 admin.py 文件 中 ， 我 们 调 
后 台中 注册 各 个 模型 。 只 有 注册 的 模型 才能 在 管理 后 台中 显示 。django.contrib.auth 应 用 也 有 admin.py 
文件 ， 因 此 管理 界面 中 才 显 示 有 “Users”" 和 “Groups”。 其 他 django.contrib 应 用 ， 如 django.con- 
trib.redirects， 也 把 自己 添加 到 管理 后 人 台中， 从 网 上 下 载 的 很 多 第 三 方 Django 应 用 程序 也 会 这 么 做 。 














用 admin.site.register()， 在 管理 











自己 的 模型 、 模 板 、 视 图 和 URL 模式 。 你 的 应 用 
这 与 设置 自己 编写 的 视图 一 样 。 你 可 以 在 你 下 
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载 的 Django 代码 基 中 查看 django/contrib/admin 里 的 代码 ， 查 看 它 的 模板 、 视 图 和 URL 配置 。 但 是 ， 
不 要 直接 修改 任何 代码 ， 因 为 里 面 有 众多 定制 管理 后 台 的 钧 子 。 阅 读 Django 管理 后 台 的 代码 时 记 住 一 
点 ， 在 读 取 模型 的 元 数据 方面 它 做 了 相当 复杂 的 操作 ， 所 以 可 能 要 花 点 时 间 才 能 理解 。 
































DD Add user | Django site a 
a 


] 127.0.0.1:8000/admin/auth/user/add 


Welcome, admin. View site / Change password / Log out 


Home » Authentication and Authorization » Users » Add 


Add user 


First, enter a username and password. Then, you'll be able to edit more user options. 


© Please correct the errors below. 
This field is required 


Username: 





This field is required. 


Password: 


This field is required 


Password confirmation: 





Save and add another Save and continue editing Bd 


图 5-5， 显 示 有 错误 的 编辑 表单 


口 Change history: admin | 
全 


3] 127.0.0.1:8000/admin/authy/user1/his 


Welcome, Nigel. View site / Change password / Log out 


Home » Authentication and Authorization » Users » admin » History 


Change history: admin 
Date/time User Action 
June 7, 2016, 4:38 p.m. admin (Nigel George) Changed first_name and last_name. 


图 5-6， 一 个 对 象 的 修改 历史 页 面 


5.2 把 模型 添加 到 Django 管理 后 台中 











有 一 个 重要 操作 我 们 还 没 做 。 我 们 要 把 自己 编写 的 模型 添加 到 管理 后 人 台中， 这 样 便 可 以 在 精美 的 界面 中 添 
加 、 修 改 和 删除 自 定义 数据 表 中 的 对 象 。 我 们 继续 以 第 4 章 开 发 的 books 应 用 为 例 。 那 个 应 用 定义 了 三 个 模 
型 : PubLisher、Author 和 Book。startapp 命令 应 该 在 books 目录 (mysite/books) 中 创建 了 admin.py 文件 ， 
如 果 没 有 ， 自 己 动手 创建 ， 然 后 输入 下 面 几 行 代码 : 





























from django.contrib import admin 
from .models import Publisher, Author, Book 
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admin.site.register(Publisher) 
admin.site.register(Author) 
admin.site.register(Book) 








上 述 代 码 告 诉 Django 管理 后 台 ， 为 这 几 个 模型 提供 界面 。 添 加 代码 之 后 ， 在 Web 浏览 器 中 访问 管理 后 台 首 
页 (http://127.0.0.1:8000/admin/) ， 你 应 该 会 看 到 一 个 “Books” 表 ， 列 出 Authors、Books 和 Publishers 链 
接 。 (可 能 要 重启 开发 服务 器 改动 才能 生效 。) 现在 ， 这 三 个 模型 的 管理 界面 完全 可 用 了 。 很 简单 吧 ! 


花 点 时 间 添 加 和 修改 记录 ， 向 数据 库 中 填充 一 些 数据 。 如 果 你 跟着 第 4 章 的 示例 做 ,创建 了 几 个 Publisher 
对 象 〔 而 且 没 删除 ) ， 在 修改 列表 页 面 会 看 到 那些 出 版 社 记录 。 


个 功能 值得 提 一 下 : 管理 后 台 能 自动 处 理 外 键 和 多 对 多 关系 (Book 模型 中 都 有 ) 。 下 面 回顾 一 下 Book 模 
型 的 代码 : 



























































class Book(models.Model): 
title = models.CharField(max_length=100) 
authors = models.ManyToManyField(Author) 
publisher = models.ForeignKey(Publisher) 
publication_date = models.DateField() 


def _ str_(self): 
return self.title 





在 Django 管理 后 人 台 的 添加 图 书页 面 (http://127.0.0.1:8000/admin/books/book/add/) ， 出 版 社 字段 (For- 
eignKey) 显示 为 选择 框 ， 作 者 字段 (ManyToManyField) 显示 为 多 选 框 。 这 两 个 字段 旁边 都 有 一 个 绿色 加 号 图 
标 ， 用 于 添加 相应 的 记录 。 


比如 说 ， 点 击 "Puplisher 字段 旁边 的 绿色 加 号 按钮 后 会 弹出 一 个 窗口 ， 用 于 添加 出 版 社 记录 。 在 弹出 窗口 中 
成 功 创建 出 版 社 记录 后 ， 添 加 图 书 表 单 会 更 新 ， 列 出 新 创建 的 出 版 社 。 真 是 太 棒 了 ! 

































































5.3 把 字段 设 为 可 选 的 








在 管理 后 台中 操作 一 会 之 后 ， 你 可 能 会 发 现 有 个 局 限 : 编辑 表单 要 求 填写 每 个 字段 ， 而 有 时 候 某 些 字段 需要 
是 可 选 的 。 比 如 说 ， 我 们 可 能 想 让 Author 模型 的 email 字段 可 选 ， 即 允许 使 用 空 字符 串 。 事 实 也 是 如 此 ， 你 
不 可 能 有 每 位 作者 的 电子 邮件 地 址 。 















































为 了 把 email 字段 设 为 可 选 的 ， 我 们 要 编辑 Author 模型 (在 mysite/books/models.py 文件 中 ) ， 为 email 字 
段 添加 blank=True 参数 ， 如 下 所 示 : 











class Author(models.Model): 
first_name = models.CharField(max_length=30) 
Last_name = models.CharField(max_length=40) 
email = models.EmailField(blank=True) 








这 个 参数 告诉 Django， 作 者 的 电子 邮件 地 址 允许 为 空 值 。 黑 认 情 况 下 ， 所 有 字段 都 设 定 了 blLank=Fatse， 意 
即 不 允许 为 空 值 。 


这 里 发 生 了 一 件 有 趣 的 事 。 和 截至 目前 ， 除 了 __str__() 方法 之 外 ， 模 型 的 作用 是 定义 数据 库 表 ， 即 与 SQL 
CREATE TABLE 语句 等 效 的 Python 代码 。 添 加 blank=True 之 后 ， 模 型 不 再 只 用 于 定义 数据 库 表 的 结构 了 。 























现在 ， 模 型 类 的 作用 变 得 丰富 了 ， 不 仅 知道 Author 对 象 是 什么 ， 还 知道 它们 能 做 什么 。email 字段 不 仅 表示 
数据 库 中 的 一 个 VARCHAR 列 ， 在 Django 管理 后 台 等 上 下 文中 ， 它 还 是 一 个 可 选 字 段 。 
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添加 bLank=True 之 后 ， 再 次 访问 “Add author 表 单 (http://127.0.0.1:8000/admin/books/author/add/) ， 你 
会 发 现 字段 的 标注 一 一 “Email” 一 一 不 是 粗 体 了 。 这 表明 ， 它 不 是 必 填 字段 了 。 现 在 添加 作者 ， 无 需 提供 电子 
邮件 地 址 ， 提 交 空 值 时 ， 不 会 显示 亮 红 色 的 “This field is required” 消 息 。 








5.3.1 把 日 期 和 数值 字段 设 为 可 选 的 


为 日 期 和 数值 字段 设 定 blank=True 时 经 常 遇 到 问题 ， 这 背后 涉及 很 多 知识 。SQL 使 用 是 一 个 特殊 的 值 表示 空 
值 一 一 NLL。 它 的 意思 是 “未 知 " 或 "无效 "， 或 者 其 他 情境 中 的 特定 意思 。 在 SQL 中 ，NULL 与 空 字符 串 不 是 一 
回 事 ， 就 像 Python 对 象 None 不 是 空 字符 串 〈"”") 一 样 。 


因此 ， 特 定 的 字符 字段 (如 VARCHAR 列 ) 的 值 既 可 以 是 WLL， 也 可 以 是 空 字 符 串 。 这 可 能 导致 意料 之 外 的 靶 
义 :“ 为 什么 在 这 个 记录 中 是 NWLL， 而 在 其 他 记录 中 是 空 字 符 串 ? 二 考 有 区 别 吗 ， 还 是 说 输入 的 数据 不 一 
致 ? ”以 及 :“ 如 何 获取 所 有 为 空 值 的 记录 ， 应 该 包含 值 为 NULL 和 空 字 符 的 记录 ， 还 是 只 选择 值 为 空 字符 串 的 
记录 ? ” 




































































为 了 避免 这 种 歧义 ，Django 自动 生成 的 CREATE TABLE 语句 (参见 第 4 章 ) 中 每 个 列 定义 都 有 NOT NULL。 例 
如 ， 下 面 是 为 Author 模型 生成 的 语句 ， 摘 自 第 4 章 ， 























CREATE TABLE "books_author" ( 
"id" serial NOT NULL PRIMARY KEY ， 
"first_name" varchar(30) NOT NULL， 
"last_name" varchar(40) NOT NULL ， 
"email" varchar(75) NOT NULL 

); 


多 数 情况 下 ， 这 种 默认 行为 对 应 用 程序 来 说 是 最 佳 选 择 ， 无 需 费力 处 理 数 据 不 一 致 。 而 且 ，Django 的 其 他 部 
分 能 很 好 地 支持 这 个 行为 ， 例 如 Django 管理 后 台 ， 当 你 留 空 字符 字段 时 ，Django 插入 数据 库 的 是 空 字符 串 
(而 不 是 NULL 值 ) 。 


但 是 ， 对 空 字 符 串 不 是 有 效 值 的 数据 库 列 类 型 (如 日 期 、 时 间 和 数字 ) 来 说 ， 这 样 处 理 不 行 。 如 果 把 空 字符 
串 插入 日 期 或 整数 列 ， 数 据 库 有 可 能 报错 一 一 这 取决 于 你 用 的 数据 库 。 (PostgreSQL 严格 ， 遇 到 这 种 情况 时 
抛 出 异常 ， MySQL 可 能 允许 这 么 做 ， 也 可 能 不 允许 ， 根 据 版 本 、 时 间 和 月 相 而 定 。) 


此 时 ， 只 能 使 用 NULL 指定 空 值 。 在 Django 模型 中 ， 指 定 接受 NULL 值 的 方式 是 为 字段 设 定 nuLL=True 参数 。 
因此 ， 说 起 来 有 点 复杂 : 如 果 想 让 日 期 字段 (如 DateField、TimeField、DateTimeField) 或 数值 字段 (如 
IntegerField、DecimalField、FloatField) 接受 空 值 ， 要 同时 添加 nuLL=True 和 blank=True。 



















































































下 面 通过 实例 说 明 。 我 们 来 修改 Book 模型 ， 人 允许 publication_date 字段 为 空 。 修 改 后 的 代码 如 下 : 





class Book(models.Model): 
title = models.CharField(max_length=100) 
authors = models.ManyToManyField(Author) 
publisher = models.ForeignKey(Publisher) 
publication_date = models.DateField(blank=True, null=True) 


添加 nuLL=True 比 添加 blank=True 复杂 ， 因 为 前 者 修改 了 数据 库 的 语义 ， 即 修改 了 CREATE TABLE 语句 ， 把 
publication_date 字段 的 NOT NULL 删 掉 了 。 为 了 完成 修改 ， 我 们 要 更 新 数据 库 。 基 于 一 些 原因 ，Django 不 会 
试图 自动 修改 数据 库 模 式 ， 所 以 每 次 对 模型 做 这 种 修改 之 后 要 自己 动手 执行 python manage.py migrate 命 
令 。 执 行 完 迁 移 之 后 ， 回 到 管理 后 台 ， 现 在 添加 图 书 表单 应 该 允许 把 出 版 日 期 设 为 空 值 了 。 
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5.4 自 定义 字段 的 标注 
































在 管理 后 台 的 编辑 表单 中 ， 各 个 字段 的 标注 根据 模型 中 字段 的 名 称 生成 。 生 成 方式 很 简单 : 把 下 划 线 替换 成 
空格 ， 再 把 第 一 个 字母 变 成 大 写 。 例 如 ，Book 模型 中 publication_date 字段 对 应 的 标注 是 “Publication 
date ”。 




















然而 ， 根 据 字 段 名 称 并 不 是 总 能 生成 好 的 标注 ， 因 此 有 时 需要 自 定义 。 自 定义 标注 的 方式 是 为 模型 字段 指定 
verbose_name 参数 。 例 如 ， 下 述 代 码 把 Author .email 字段 的 标注 改 为 “e-mail”( 中 间 有 个 连 字 符 ) : 





class Author(models.Model): 
first_name = models.CharField(max_length=30) 
Last_name = models.CharField(max_length=40) 
email = models.EmailField(blank=True, verbose name='e-mail') 





修改 之 后 ， 再 次 访问 编辑 作者 表单 ， 你 会 发 现 显示 的 是 新 标注 。 注 意 ， 除 非 始 终 应 该 为 大 写 (如 "USA 
state") ,否则 不 应 该 把 verbose_name 值 的 首 字母 设 为 大 写 。 如 果 需 要 ， Django 会 自动 把 首 字 母 变 成 大 写 ， 
在 不 需要 大 写 的 地 方 ， 则 直接 使 用 verbose_name 的 值 。 





























5.5 自 定义 ModelAdmin 类 
目前 我 们 所 做 的 改动 ， 添 加 blank=True、null=True 和 verbose_name， 修 改 的 其 实 都 是 模型 层 ， 只 是 碰巧 管理 
后 台 有 用 到 ， 还 未 涉及 管理 后 台 自 身 。 


除 此 之 外 ，Django 管理 后 台 也 提供 了 丰富 的 选项 ， 可 以 定制 处 理 具体 模型 的 方式 。 这 些 选 项 在 ModelAdmin 
类 中 ， 这 些 类 包含 特定 管理 后 台 实例 中 特定 模型 的 配置 。 









































5.5.1 自 定 义 修改 列表 


我 们 将 指定 Author 模型 的 修改 列表 中 显示 的 字段 ， 以 此 说 明 如 何 定制 管理 后 台 。 黑 认 情况 下 ， 修 改 列表 显示 
的 是 各 个 对 象 的 _str__() 方法 返回 的 结果 。 在 第 4 章 ， 我 们 为 Author 对象 定 义 了 _str__() 方法 ， 显 示 名 
字 和 姓 : 




















class Author(models.Model): 
first_name = models.CharField(max_length=30) 
Last_name = models.CharField(max_length=40) 
email = modeLs.EmaiLFieLd(bLank=True，verbose_name ='e-mail') 


def _ str_(self): 
return u'%s %s' % (self.first name, self.last_name) 





因此 ，Author 对 象 的 修改 列表 中 显示 各 个 作者 的 名 字 和 姓 ， 如 图 5-7 所 示 。 
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口 Select authorto change| Xx 


所 CG 省 | D127.0.0.1:8000/admin/books/author/ 汉中 唱 三 


Welcome, Nigel. View site / Change password / Log out 
Home » Books » Authors 
Select author to change perpmrpe 
Action: | -———————— v|Gol 0of3 selected 
Author 
Peter Smith 
Barry jones 


Nigel George 


3 authors 


图 5-7， 作 者 的 修改 列表 页 面 


我 们 可 以 改进 这 种 默认 行为 ， 在 修改 列表 中 添加 几 个 其 他 字段 。 比 如 说 ， 可 以 在 列表 中 显示 作者 的 电子 邮件 
地 址 ， 另 外 ， 如 果 能 按照 名 字 和 姓 排 序 就 好 了 。 为 此 ， 要 为 Author 模型 定义 一 个 ModelAdmin 子 类 。 这 个 类 
是 定制 管理 后 台 的 关键 ， 其 中 最 基本 的 一 件 事 是 指定 修改 列表 页 面 显 示 的 字段 。 参 照 下 述 代 码 修改 admin.py 
文件 : 








from django.contrib import admin 
from mysite.books.models import Publisher, Author, Book 


class AuthorAdmin(admin.ModelAdmin): 
list display = ('first name', 'last_ name', 'email') 


admin.site.register(Publisher) 
admin.site.register(Author, AuthorAdmin) 
admin.site.register(Book) 


我 们 做 了 以 下 几 件 事 : 


。 定义 AuthorAdmin 类 。 它 是 django.contrib.admin.ModeLAdmin 的 子 类 ， 存 放 指 定 模型 在 管理 后 台中 的 
自 定义 配置 。 我 们 只 做 了 一 项 定制 ，list_display， 把 它 的 值 设 为 一 个 元 组 ， 指 定 要 在 修改 列表 页 面 
显示 的 字段 名 称 。 当 然 ， 模 型 中 必须 有 这 些 字段 。 


。 修改 admin.site.register() 调用 ， 在 Author 后 面 添加 AuthorAdmin。 你 可 以 把 这 行 代码 理解 为 “以 Au- 
thorAdmin 中 的 选项 注册 Author 模型 ”"。admiin.site.register() 函数 的 第 二 个 参数 可 选 ， 其 值 是 一 个 
ModelAdmin 子 类 。 如 果 不 指定 第 二 个 参数 (Publisher 和 Book 模型 就 是 这 样 ) ，Django 使 用 默认 选项 
注册 模型 。 




















修改 之 后 ， 刷 新 作者 的 修改 列表 页 面 ， 你 会 看 到 现在 显示 了 三 列 : 名 字 、 姓 和 电子 邮件 地 址 。 此 外 ， 点 击 这 
三 列 的 表 头 都 可 以 排序 各 列 〈 见 图 5-8) 。 
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DD Select authorto change | Xx 


€ CG 全 口 127.0.0.1:8000/admin/books/author 


WO 和 唱 三 





Home » Books >» Authors 


Select author to change 


Action: | -—--—-——— 
First name 
Peter 
Barry 
Nigel 


3 authors 


5-8， 添 加 List_display 之 后 的 作者 修改 列表 页 面 


接 下 来 ,添加 一 个 简单 的 搜索 框 。 在 AuthorAdmin 类 中 添加 search_fields: 


v |Gol 0 of 3 selected 
Last name 
Smith 
Jones 


Ceorge 


class AuthorAdmin(admin.ModelAdmin): 
list display = ('first name', 'last_ name', 'email') 


search fields = ('first name', 'last_name') 





Welcome, Nigel. View site / Change password / Log out 


Email 

peter@example.com 
barry@example.com 
nigel@example.com 


刷新 浏览 器 中 的 页 面 ， 应 该 会 在 页 面 顶部 看 到 一 个 搜索 框 (图 5-9) 。 我 们 刚刚 添加 的 代码 让 管理 后 台 的 修 





改 列表 页 面 增加 一 个 搜索 框 ， 用 于 搜索 first_name 和 last_name 字段 。 正 如 用 户 期 待 的 那样 ， 这 个 

















索 框 不 


区 分 大 小 写 ， 而 且 两 个 字段 都 搜索 。 假 如 搜索 字符 串 “bar”"， 会 搜 到 名 字 为 Barney 的 作者 和 姓 为 Hobarson 的 


DD Select authorto change| x 


作者 。 


€ G 和 骆 | D127.0.0.1:8000/admin/books/author/ 


Home » Books » Authors 


Select author to change 








Q | Search 
Action- | -—----——- 9 | Gol 0of 3 selected 
First name Last name 
peter Smith 
本 Barry Jones 
Nigel Ceorge 
3 authors 


图 5-9， 添 加 search_fields 之 后 的 作者 修改 列表 页 面 





下 面 为 Book 模型 的 修改 列表 页 和 








[添加 几 个 日 期 过 滤 央 : 





ww 和 唱 三 


Welcome, Nigel. View site / Change password / Log out 


Email 

peter@example.com 
barry@example.com 
nigel@example.com 
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from django.contrib import admin 
from mysite.books.models import Publisher, Author, Book 


class AuthorAdmin(admin.ModelAdmin): 
list display = ('first name', 'last name', 'email') 
search fields = ('first name', 'last_ name') 


class BookAdmin(admin.ModelAdmin): 
list display = ('title', 'publisher', 'publication date') 
list filter = ('publication date',) 


admin.site.register(Publisher) 
admin.site.register(Author, AuthorAdmin) 
admin.site.register(Book, BookAdmin) 


这 一 次 定制 的 是 另 一 个 模型 的 选项 ， 因 此 定义 一 个 单独 的 ModelAdmin 子 类 ，BookAdmin。 首 先 ， 定 义 
list_display 属性 ， 让 修改 列表 好 看 一 些 。 然 后 ， 为 List_fitter 属性 赋值 一 个 字段 元 组 ， 在 修改 列表 页 面 
的 右边 创建 过 滤器 。Dijango 为 日 期 字段 提供 了 几 个 便利 的 过 滤器 :“Today”( 今 天 ) 、“Past7 days”( 过 去 7 
天 ) 、“This month”( 本 月 ) 和 “This year”( 本 年 ) 一 一 这 些 是 Django 的 开发 者 觉得 过 滤 日 期 时 最 常用 的 。 
这 些 过 滤器 如 图 5-10 所 示 。 


口 Select book to change1D x 


€ @ 省 | [D127.0.0.1:8000/admin/books/book/ a 唱 3 





























Welcome, Nigel. View site / Change password / Log out = 
Home » Books » Books 


Select book to change 


Add book 十 
Action: | 一 -一 -一 v |IGo| 0 of 2 selected 
Title Publisher Publication date By publication date 
Any date 
A Really Cool Book Book Publishing Inc June 7, 2016 Today 
Mastering Django: Core CNW Independent Publishing June 7, 2016 a 7 days 
his month 
This year 
2 books 


图 5-10， 添加 list_filter 之 后 的 图 书 修改 列表 页 面 


list_filter 也 能 处 理 其 他 类 型 的 字段 ， 而 非 DateField 一 个 。 (比如 说 ， 可 以 试 试 BooleanField 和 For- 
eignKey 字段 。) 只 要 有 超过 两 个 值 供 选 择 ， 过 滤器 就 会 显示 。 提 供 日 期 过 滤器 的 另 一 种 方法 是 使 用 
date_hierarchy 选项 ， 如 下 所 示 : 





class BookAdmin(admin.ModeLAdmin) : 
list display = ('title', 'publisher','publication date') 
list filter = ('publication date',) 
date_hierarchy = 'publication_date' 





添加 这 个 选项 之 后 ， 修 改 列表 上 边 会 显示 一 个 日 期 层级 导航 栏 ， 如 图 5-11 所 示 。 这 个 导航 栏 先 显示 年 份 ， 然 
后 向 下 显示 月 份 和 具体 某 一 天 。 
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入 @ 省 | D127.0.0.1:8000/admin/books/book/ 


克昌 宋 = 三 
Welcome, Nigel View site / Change password / Log out = 
Home » Books » Books 
Select book to change Add book 十 
2015 2016 ee 
Action: | -—---—-——— v |Gol 0 of2 selected dr date 
Title Publisher Publication date Today 
A Really Cool Book Book Publishing Inc June 7, 2016 Past 7 days 
Mastering Django: Core GNW Independent Publishing Sept. 9, 2015 Ue 


This year 
2 books 


图 5-11， 添 加 date_hierarchy 后 的 图 书 修改 列表 页 面 


Nm 
y 于 
/ 世 、》 





date_hierarchy 的 值 是 一 个 字符 串 ， 不 是 元 组 ， 因 为 只 能 使 用 一 个 日 期 字段 创建 层级 导航 。 最 后 ， 修 
改 默 认 的 排序 方式 ， 让 修改 列表 页 面 的 图 书 始 终 以 出 版 日 期 倒序 排列 。 默 认 情 况 下 ， 修 改 列表 根据 模型 中 
class Meta (参见 第 4 章 ) 里 的 ordering 属性 排序 ， 不 过 我 们 没 设 定 ， 因 此 没有 顺序 。 


class BookAdmin(admin.ModeLAdmin) : 








list display = ('title', 'publisher','publication date') 
list filter = ('publication_date',) 

date_hierarchy = 'publication_date' 

ordering = ('-publication date',) 


ModeLAdmin 子 类 中 的 ordering 选项 与 模型 的 class Meta 中 的 ordering 属性 的 作用 完全 一 样 ， 不 过 只 使 用 列 
表 中 的 第 一 个 字段 名 称 。ordering 选项 的 值 是 一 个 字段 名 称 列表 或 元 组 ， 如 果 想 倒序 ， 加 上 减 号 即 可 。 刷 新 
图 书 修改 列表 ， 看 看 变化 。 注 意 ,“Publication date” 表 头 中 有 个 小 箭头 ， 指 明 记 录 的 排列 顺序 (图 5-12) 。 





口 Select book to change1D x 


所 C 人 | BD 127.0.0.1:8000/admin/books/book/ OO 向 三 
Welcome, Nigel. View site / Change password / Log out = 
Home » Books >» Books 
Select book to change Add book 十 
2015 2016 Pe 
Action: | 一 -一 一 一 vv|Gol 0of2selected By publication date 
Any date 
Title Publisher Publication date “ Today 
A Really Cool Book Book Publishing Inc June 7, 2016 NN Past 7 days 
This month 
Mastering Django: Core CNW Independent Publishing Sept. 9, 2015 This year 


2 books 


图 5-12， 添加 ordering 后 的 图 书 修改 列表 页 面 


至 此 ， 我 们 介绍 了 主要 的 修改 列表 选项 。 通 过 这 些 选 项 ， 只 需 几 行 代码 就 能 得 到 可 在 生产 环境 使 用 的 强大 的 
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数据 编辑 界 本 








o 





5.5.2 自 定 义 编辑 表单 














与 修改 列表 一 样 ， 编 辑 表单 的 很 多 方面 也 可 以 定制 。 首 先 ， 我 们 来 定制 字段 的 排序 方式 。 默 认 情 况 下 ， 编 辑 
表单 中 的 字段 顺序 与 在 模型 中 的 定义 顺序 一 致 。 我 们 可 以 在 ModelAdmin 子 类 中 使 用 fields 选项 修改 排序 : 


















































class BookAdmin(admin.ModelAdmin): 
list display = ('title', 'publisher', 'publication date') 
list filter = ('publication date',) 
date_hierarchy = 'publication_date' 
ordering = ('-publication_date',) 
fields = ('title', 'authors', 'publisher', 'publication date') 






































这 样 修改 之 后 ， 图 书 的 编辑 表单 会 使 用 指定 的 顺序 显示 各 个 字段 。 在 书 名 后 面 显示 作者 稍微 符合 直觉 。 当 
然 ， 字段 的 顺序 应 该 根据 输入 数据 的 流程 而 定 。 世 界 上 没有 两 个 表单 是 相同 的 。 






















































































fields 选项 还 有 一 个 作用 : 排除 特定 的 字段 ， 禁 止 编辑 。 只 需 去 掉 想 排除 的 字段 即 可 。 如 果 你 只 相信 管理 员 
了 能力 编 辑 数据 的 某 些 部 分 ， 或 者 某 些 字段 由 外 部 的 自动 化 流程 修改 ， 就 可 以 这 么 做 。 

























































































例如 ， 在 这 个 书籍 数据 库 中 ， 我 们 可 以 隐藏 publication_date 字段 ， 禁 止 编辑 : 











class BookAdmin(admin.ModeLAdmin) : 
list display = ('title', 'publisher','publication_date') 
list filter = ('publication date',) 
date_hierarchy = 'publication date' 
ordering = ('-publication date',) 
fields = ('title', 'authors', 'publisher') 























这 样 修改 之 后 ， 通 过 图 书 的 编辑 表单 无 法 指定 出 版 日 期 。 如 果 你 是 编辑 ， 不 想 让 作者 把 出 版 日 期 往 后 退 ， 就 
可 以 这 么 做 。 (当然 ， 这 纯粹 是 个 虚构 的 例子 。) 用 户 使 用 这 个 不 完整 的 表单 添加 新 图 书 时 ，Django 会 把 
publication_date 设 为 None， 所 以 那个 字段 要 指定 nuLL=True 参数 。 

































































编辑 表单 中 另 一 个 经 常 需要 定制 的 字段 是 多 对 多 关系 字段 。 前 文 已 经 说 过 ， 管 理 后 台 为 多 对 多 关系 字段 显示 
的 是 多 项 选择 框 ， 这 是 最 符合 逻辑 的 HTML 输入 控件 ， 但 是 多 项 选择 框 不 易 使 用 。 如 果 想 选择 多 个 项 目 ， 要 
按 住 Ctrl 键 (Mac 上 的 Command 键 ) 。 
































管理 后 台 提 供 了 解说 文本 ， 但 是 有 几 百 个 选项 时 还 是 不 灵 便 。 管 理 后 台 为 此 提供 的 解决 方案 是 filter_hori- 
zontal 选项 。 我 们 把 它 添加 到 BookAdmin 中 ， 看 看 效果 : 





class BookAdmin(admin.ModeLAdmin) : 
list display = ('title', 'publisher','publication date ' ) 
list filter = ('publication date',) 
date_hierarchy = 'publication_date' 
ordering = ('-publication_date',) 
filter_horizontal = ('authors',) 














(如 果 你 一 直 跟 着 我 做 ， 注 意 ， 我 们 删除 了 fields 选项 ， 让 所 有 字段 都 在 编辑 表单 中 显示 出 来 。) 刷新 图 书 
的 编辑 表单 ， 你 会 看 到 “Authors” 部 分 现在 使 用 一 个 精美 的 JavaScript 过 滤器 界面 ， 可 以 动态 搜索 选项 ， 把 指 
定 的 作者 从 “Available authors” 移 到 “Chosen authors” 框 中 (以 及 反 向 移动 ) 。 
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二 一 口 X 
D Add beok1Diango site ac x WN 


所 CG 省 六 127.0.0.1:8000/admin/books/book/add ye oO 咀 三 


Welcome, Nigel. View site / Change password / Log out = 
Home » Books » Books » Add book 


Add book 


Title: | 








Authors: 
Available authors © 全 


Q 

Nigel Ceorge 
Barry jones 
Peter Smith 


Choose al 全 Remove all 


Publisher: | ----— 7 了] 中 


Publication Today 1 上 站 
date: 


Save and add another Save and continue editing | Save | 和 


图 5-13， 添加 filter_horizontal 后 的 图 书 编辑 表单 





如 果 多 对 多 字段 中 的 项 目 超过 10 个 ， 我 强烈 建议 使 用 filter_horizontal。 这 个 过 滤器 界面 比 简单 的 多 项 选 
择 框 容易 使 用 多 了 。 此 外 注意 ，filter_horizontal 可 以 指定 多 个 字段 ， 在 元 组 中 列 出 各 个 字段 的 名 称 即 可 。 








ModeLAdmin 子 类 也 支持 filter_vertical 选项 。 它 的 作用 与 filter_horizontal 完全 一 样 ， 不 过 得 到 的 
JavaScript 界面 是 纵向 排列 的 两 个 选择 框 ， 而 不 是 横向 的 。 使 用 哪个 全 看 个 人 喜好 。 






























































filter_horizontal 和 filter_vertical 只 能 用 于 多 对 多 字段 ， 不 能 用 于 外 键 字 段 。 默 认 情 况 下 ， 管 理 后 台 为 
外 键 字 段 显 示 一 个 简单 的 <select> 菜单 ， 不 过 与 多 对 多 字段 一 样 ， 有 时 你 不 想 费力 气 从 下 拉 菜 单 中 找 出 所 需 
的 对 象 。 








例如 ， 书 籍 数据 库 不 断 变 大 ， 包 含 几 千 个 出 版 社 ， 添 加 图 书 表 单 要 花 一 些 时 间 才 能 加 载 ， 因 为 要 加 载 每 个 出 
版 社 记 录 ， 在 <select> 菜单 中 显示 。 











为 了 解决 这 个 问题 ， 可 以 使 用 raw_id_fields 选项 : 


class BookAdmin(admin.ModelAdmin): 
list display = ('title', 'publisher','publication date') 
list filter = ('publication date',) 
date_hierarchy = 'publication date' 
ordering = ('-publication_date',) 
filter_horizontal = ('authors',) 
raw_id fields = ('publisher',) 














这 个 选项 的 值 是 一 个 外 键 字 段 名 称 元 组 ， 各 个 字段 在 管理 后 台中 显示 为 简单 的 文本 输入 框 (<input 
type="text">) ， 而 不 是 <select> 菜单 ， 如 图 5-14 所 示 。 
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D Add beok1Diango site ac x WN 


所 @ 省 | D127.0.0.1:8000/admin/books/book/add 


Home » Books » Books » Add book 
Add book 


Title: 








Authors: 
Available authors © 


Q 

Nigel Ceorge 

Barry jones 

Peter Smith 

Choose alD 
Mak 

Publisher Q N 
Publication Today 1 月 
date: 























5.6 用 户 、 分 组 和 权限 











二 一 口 X 


OO 遇 三 


Welcome, Nigel. View site / Change password / Log out 


Cy Remove all 


Save and add another Save and continue editing | Save | - 


图 5-14， 添 加 raw_id_fields 后 的 图 书 编辑 表单 


你 是 以 超级 用 户 身份 登录 的 ， 有 权限 创建 、 编 辑 和 删除 任何 对 象 。 当 
不 是 每 个 人 都 可 以 或 应 该 是 超级 用 户 。Django 的 管理 后 台 也 有 权限 系统 ， 让 你 给 特定 用 户 赋予 访问 特定 功能 

















在 这 个 输入 框 中 输入 什么 呢 ? 数据 库 中 出 版 社 记 录 的 ID 。 鉴 于 人 类 通常 不 善于 记忆 数字 ， 旁 边 还 有 一 个 放大 
镜 图 标 ， 点 击 后 弹出 一 个 窗口 ， 用 于 选择 要 添加 的 出 版 社 。 





然 ， 不 同 的 环境 需要 不 同 的 权限 系统 ， 























的 权限 。 用 户 帐 号 应 该 是 通用 的 、 独 立 于 管理 界 


账户 。 


1， 在 外 部 仍 可 以 使 











用 ， 但 是 我 们 现在 仍 把 他 们 当做 管理 员 


第 11 章 将 说 明 如 何 使 用 Django 的 身份 认证 系统 管理 全 站 的 用 户 〈 即 不 仅 是 管理 后 台 的 用 户 ) 。 用 户 和 权限 





可 以 像 其 他 对 和 象 一 样 在 管理 界面 中 编辑 。 本 章 前 鱼 
































于 定义 允许 用 户 在 管理 界面 中 做 什么 。 首 先是 三 个 布尔 值 旗 标 : 


| 介绍 管理 后 台 的 “Users”" 和 “Groups” 部 分 时 已 经 有 所 涉及 。 





正如 你 期 望 的 ， 用 户 对 象 有 一 些 标准 的 字段 :用 户 名 、 密 码 、 电 子 邮 件 和 真实 姓名 。 此 外 ， 还 有 一 些 字段 用 


。“Active” 控 制 是 否 激 活用 户 。 如 果 未 勾 选 ， 即 便 用 户 使 用 有 效 的 密码 也 无 法 登录 。 











。 “Staff status” 控 制 是 否 允许 用 户 登 录 管 理 界 再 


























的 。 

















i ( 即 是 否 把 用 户 当 做 组 织 中 的 一 员 ) 。 因 为 这 个 用 户 系统 
也 用 于 控制 面向 公众 的 网 站 ( 即 前 全 ， 参 见 第 11 章 ) ， 所 以 这 个 旗 标 对 公开 用 户 和 管理 员 是 有 区 别 

















。“Superuser status ”为 用 户 赋予 所 有 权限 ， 可 以 在 管理 界面 中 添加 、 编 辑 和 删除 任何 对 象 。 如 果 勾 选 ， 用 





户 的 常规 权限 (即使 没有 ) 不 再 考虑 。 
































“普通 的 ”管理 员 ， 即 已 激活 且 不 是 超级 用 户 ， 所 具有 











的 管理 权限 是 一 项 项 赋予 的 。 可 在 管理 界面 中 编辑 的 对 











象 〈 如 图 书 、 作 者 和 出 版 社 ) 有 三 个 权限 : 创建 权限 、 编 辑 权 限 和 删除 权限 。 为 用 户 赋予 权限 就 是 允许 用 户 
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执行 相应 的 操作 。 新 建 的 用 户 没有 任何 权限 ， 如 果 需 要 特定 权限 ， 要 由 你 赋予 。 


例如 ， 可 以 为 用 户 赋予 添加 和 修改 出 版 社 的 权限 ， 但 是 不 允许 删除 。 注 意 ， 这 些 权 限 是 针对 每 个 模型 的 ， 而 
不 是 每 个 对 象 。 因 此 ， 可 以 允许 John 修改 任何 一 本 书 ， 但 是 不 能 允许 他 只 能 修改 Apress 出 版 的 书 。 针 对 各 
个 对 象 的 权限 更 复杂 ， 不 在 本 书 的 讨论 范围 之 内 ， 不 过 Django 的 文档 中 有 说 明 。 


编辑 用 户 和 权限 的 权限 也 由 权限 系统 控制 。 如 果 为 某 人 赋予 编辑 用 户 的 权限 ， 他 就 能 编辑 自己 
的 权限 一 一 这 可 能 不 是 你 想 要 的 行为 ! 给 用 户 赋予 编辑 用 户 的 权限 ， 其 实 就 相当 于 把 他 变 成 超 
用 用 启 。 













































































用 户 还 可 以 分 组 。 一 个 分 组 中 的 所 有 成 员 都 有 那 一 组 具有 的 全 部 权限 。 使 用 分 组 便于 为 多 个 用 户 赋予 相同 的 
权限 。 











5.7 何 时 以 及 为 何 使 用 管理 界面 

















至 此 ， 你 应 该 基本 知道 该 如 何 使 用 Django 的 管理 后 台 了 。 不 过 ， 我 想 说 明 一 下 何 时 以 及 为 何 使 用 管理 后 台 ， 
以 及 何 时 无 需 使 用 。 


对 想 输入 数据 的 非 技术 人 员 来 说 ，Django 的 管理 后 台 特 别 有 用 ， 毕 竞 ， 这 就 是 管理 后 台 的 目的 。 在 Django 
诞生 的 新 闻 业 中 ， 一 个 在 线 功 能 (例如 市 政 供水 水 质 特别 报道 ) 的 开发 过 程 通常 是 这 样 的 : 























。 负责 该 项 目的 记者 与 一 位 开发 者 碰头 ， 指 出 所 需 的 数据 。 
。 开发 者 设计 满足 需求 的 Django 模型 ， 然 后 打开 管理 后 台 给 记者 看 。 
。 记者 审查 管理 后 人 台 ， 及 时 指出 缺少 或 多 余 的 字段 。 开 发 者 不 断 修改 模型 。 


。 得 到 满意 的 模型 之 后 ， 记 者 开始 在 管理 后 台中 输入 数据 。 与 此 同时 ， 程 序 员 可 以 集中 精力 开发 面向 公 
众 的 视图 /模板 〈 即 开发 过 程 中 有 趣 的 部 分 ) 。 


























也 就 是 说 ，Django 的 管理 界面 为 内 容 制作 人 员 和 程序 员 都 提供 了 便利 的 工具 。 除 了 输入 数据 之 外 ， 管 理 后 台 
还 有 很 多 用 处 : 





























。 审查 数据 模型 : 定义 几 个 模型 之 后 ， 可 以 在 管理 界面 中 查看 ， 输 入 一 些 虚 拟 数据 。 有 时 ， 在 这 个 过 程 
中 能 够 发 现 数据 建 模 等 问题 。 

。 管理 从 别处 得 到 的 数据 : 对 依靠 外 部 源 (例如 用 户 或 Web 爬虫 ) 提供 数据 的 应 用 程序 来 说 ， 通 过 管理 
后 全 便于 审查 或 编辑 数据 。 你 可 以 把 管理 后 台 看 做 数据 库 命令 行 工具 的 另 一 个 版 本 ,虽然 不 那么 强 
大 , 但 是 足够 便利 。 

。 临时 的 数据 管理 应 用 : 你 可 以 使 用 管理 后 台 构 建 一 个 特别 轻 量 级 的 数据 管理 应 用 ， 例 如 记录 花 销 。 如 
果 只 构建 给 自己 用 的 功能 ， 而 不 面向 公众 ， 管 理 后 台 能 节省 很 多 时 间 。 在 这 个 意义 上 ， 管 理 后 台 相 当 
于 增强 版 关系 型 电子 表格 。 



























































然而 ， 管 理 后 台 不 是 万 能 的 。 不 应 该 把 它 当 做 数据 的 公开 界面 ， 它 也 不 具有 复杂 的 排序 和 搜索 功能 。 前 面 说 
过 ， 管 理 后 台 是 供 授信 的 网 站 管理 员 使 用 的 。 唯 有 记 住 这 一 点 ， 才 能 有 效 利用 管理 后 台 。 






































5.8 接 下 来 





至 此 ， 我 们 创建 了 几 个 模型 ， 也 配置 了 一 流 的 编辑 界面 。 下 一 章 将 换个 话题 ， 进 入 Web 开发 的 实质 阶段 : 创 
建 和 处 理 表 单 。 
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HTML 表 生 
单 ， 再 到 





复杂 的 数据 输入 界 画 


本 章 说 明 如 何 使 用 Django 访 
和 Form 对 象 。 














6.1 从 请 求 对 象 中 获取 数据 


PN 


第 2 





区 | 


章 首 次 介 委 








如 视图 函数 时 提 到 过 





问 、 验 证 和 处 理 


是 交互 式 网 站 的 基本 组 成 部 分 ， 从 Google 网 站 
i， 都 能 见 到 表单 的 身影 。 


























EE 用户 提交 的 表单 数据 。 在 这 个 过 程 中 ， 






































数 都 是 











一 个 HttpRequest 对 象 ， 如 下 耳 





| 的 hello() 视 





from django.http import HttpResponse 


def hello(request): 


return HttpResponse("Hello world") 


HttpRequest 对 象 ， 如 这 里 的 request 








所 示 : 





HttpRequest 对 象 ， 但 是 没有 细 讲 。i 


区 | 
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FP 简单 的 搜索 框 ， 到 无 处 不 在 的 博客 评论 提交 表 








我 们 将 介绍 HttpRequest 








参数 ， 














些 有 



































可 用 。 执 行 视 图 函数 时 ， 
网 站 中 的 某 个 页 面 ) 的 信息 。 











6.1.1 关于 URL 的 信息 





HttpRequest 对 象 中 有 一 些 关 于 当前 所 请 求 URL 的 信息 











( 表 6-1) 。 


的 属性 和 方法 ， 你 应 该 有 所 了 解 ， 这 样 才 知 道 有 什么 
可 以 使 用 这 些 属 性 获取 关于 当 前 请 求 〈 即 用 户 在 Web 浏览 器 中 访问 Django 驱动 的 








表 6-1，HttpRequest 对 象 的 方法 和 属性 

属性 /方法 说 明 示例 
完整 的 路 径 ， 不 含 域名 ， 但 是 

request.path 完整 的 路 径 ， 不 含 域名 ， 但 是 包 “/hello/” 


request.get_host() 


request.get_full_path() 


request.is_secure() 


含 前 导 和 斜 线 























包含 查询 字符 串 (如 


的 路 径 

















主机 名 ( 即 通常 所 说 的 “域名 ”) 





果 有 的 话 ) 














“]27.0.0.1:8000” 或 “Www.exam- 
ple.com” 


“/hello/?print=true” 


通过 HTTPS 访问 时 为 True,， 天 


True 或 FaLse 





















































则 为 False 
在 视图 中 一 定 要 使 用 这 些 属性 或 方法 ， 不 能 硬 编码 URL。 这 样 写 出 的 代码 更 灵活 ， 便 于 在 不 同 的 地 方 复 用 。 
下 面 举 个 简单 的 例子 : 
# 不 好 


def current_ url_ view bad(request): 


return HttpResponse("Welcome to the page at /current/") 
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# 好 
def current_UrL_view_good(request) : 
return HttpResponse("NeLcome to the page at %s" % request.path) 


6.1.2 关于 请 求 的 其 他 信息 


request.META 的 值 是 一 个 Python 字典 ， 0 HTTP 首部 ， 例 如 用 户 的 卫 地址 和 用 户 代 理 (user 
agent， 通 常 是 Web 浏览 器 的 名 称 和 版 本 ) 。 ， 具 体 包含 哪些 首部 取决 于 用 户 发 送 了 什么 首部 ， 以 及 
Web 服务 器 返回 了 什么 首部 。 这 个 字典 中 涪 见 的 几 个 健 有 。 




















。 HTTP_REFERER: 人 站 前 的 URL (可 能 没有 ) 。 (注意 ， 要 使 用 错误 的 拼写 ， 即 REFERER。 ) 


。 HTTP_USER_AGENT: 浏览 器 的 用 户 代 理 (可 能 没有 ) 。 例 如 : "Mozilla/5.0 (X11; U; Linux i686; fr- 
FR; rv:1.8.1.17) Gecko/20080829 Firefox/2.0.0.17"。 


。 REMOTE_ADDR: 客户 端的 耻 地 址 ， 例 如 "12.345.67.89"。 (如 果 请 求 经 由 代理 ， 这 个 首部 的 值 可 能 
组 卫 地址 ， 以 逗号 分 隔 ， 例 如 "12.345.67.89,23.456.78.90"。) 


























注意 ， 因 为 request.META 是 个 普通 的 Python 字典 ， 所 以 尝试 访问 不 存在 的 键 时 ， 抛 出 KeyError 异常 。 
(HTTP 首部 是 外 部 数据 ， 即 由 用 户 的 浏览 器 提交 ， 因 此 不 能 完全 相信 ， 当 某 个 首部 为 空 或 不 存在 时 ， 应 该 
让 应 用 程序 优雅 失败 。) 为 了 处 理 未 定义 的 键 ， 应 该 使 用 try/except 子 句 ， 或 者 get() 方法 : 















































# 不 好 

def ua_dispLay_bad(request) : 
ua = request.META['HTTP_USER_AGENT'] # 可 能 抛 出 KeyError 
return HttpResponse("Your browser is %s" % ua) 


# 好 (有 版 本 1) 
def ua display_goodi(request): 
蕊 FS 
ua = request.META[ 'HTTP_USER_AGENT ' ] 
except KeyError: 
ua = "unknown' 
return HttpResponse("Your browser is %s" % ua) 


# 好 (版 本 2) 

def ua_display_good2(request): 
ua = request.META.get('HTTP_USER_AGENT' ，'unknown ' ) 
return HttpResponse("Your browser is %s" % ua) 























建议 你 编写 一 个 简单 的 视图 ， 显 示 request.META 中 的 所 有 信息 ， 以 便 查 阅 。 下 面 是 个 示例 : 




















def display_meta(request): 
values = request.META.items() 
values.sort() 
html = [] 
for k, v in values: 
html .append('<tr><td>%s</td><td>%s</td></tr>' % (k, v)) 
return HttpResponse('<table>%s</table>' % '\n'.join(html)) 


查看 请 求 对 象 中 有 哪些 信息 的 另 一 个 好 办 法 是 仔细 分 析 Django 的 错误 页 面 ， 里 面 有 很 多 有 用 的 信息 ， 包 括 全 
部 HTTP 首部 和 其 他 请 求 信息 (如 request.path) 。 
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6.1.3 关于 提交 数据 的 信息 








除了 关于 请 求 的 基本 元 数据 之 外 ，HttpRequest 对 象 还 有 两 个 属性 包含 用 户 提交 的 信息 : request.GET 和 re- 
quest.P0ST。 这 两 个 属性 的 值 都 是 类 似 字典 的 对 象 ， 分 别 用 于 获取 GET 和 POST 数据 。P0S5T 数据 一 般 由 HIML 
表单 提交 ， 而 GET 数据 既 可 以 来 自 表 单 ， 也 可 以 来 自 页 面 URL 中 的 查询 字符 串 。 


类 似 字典 的 对 象 


我 们 说 request.GET 和 request.P0ST 是 “类 似 字 典 的 对 象 "， 意 思 是 它们 的 行为 与 标准 的 Python 
字典 相似 ， 但 是 不 完全 一 样 。 例 如 ，request.GET 和 request.POST 都 有 get()、keys() 和 val- 
ues() 等 方法 ， 而 且 可 以 使 用 for key in request.GET 迭代 键 。 那 么 ， 为 什么 不 干脆 使 用 字典 
呢 ? 因为 request.GET 和 request.P0ST 都 有 常规 的 字典 没有 的 额外 方法 ， 稍 后 会 做 介绍 。 你 可 
能 见 过 类 似 的 表述 ， 例 如 ”类似 文件 的 对 象 ”， 这 种 对 象 有 些 基 本 的 方法 ， 如 read()， 行 为 与 
“真正 的 "文件 对 象 相似 。 

































































6.2 一 个 简单 的 表单 处 理 示例 


我 们 继续 以 图 书 、 作 者 和 出 版 社 为 例 。 下 面 创建 一 个 简单 的 视图 ， 让 用 户 通过 书 名 搜索 数据 库 中 的 图 书 。 一 
般 来 说 ， 表 单 分 为 两 部 分 : 用 户 界面 HIML 和 处 理 提 交 数 据 的 后 端 视图 代码 。 前 半 部 分 很 简单 ， 只 需 编写 一 
个 视图 ， 显 示 搜 索 表 单 ; 





from django.shortcuts import render 


def search form(request): 
return render(request, 'search form.html') 





读 过 第 3 章 我 们 知道 ， 视 图 可 以 放 在 Python 路 径 中 的 任何 位 置 。 但 是 ， 为 了 便于 增强 ， 我 们 把 它 放 在 books/ 
views .py 文件 中 。 对 应 的 search_form.html 模板 如 下 所 示 : 





<html> 
<head> 
<title>Search</title> 
</head> 
<body> 
<form action="/search/" method="get"> 
<input type="text" name="q"> 
<input type="submit" value="Search"> 
</form> 
</body> 
</html> 





把 这 个 文件 保存 在 第 3 章 创建 的 mysite/templates 目录 中 。 此 外 ， 也 可 以 新 建 books/templates 文件 夹 。 此 
时 应 该 把 设置 文件 的 'APP_DIRS ' 设 为 True。urls.py 文件 中 的 URL 模式 如 下 : 





from books import views 


urlpatterns = [ 
i 
url(r'^search-form/$', views.search_form), 
i 
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(注意 ， 我 们 直接 导入 views 模块 ， 而 不 是 from mysite.views import search_form， 因 为 前 者 更 简单 。 第 7 
章 将 详细 说 明 这 种 导 和 人 方式。) 此 时 ， 启 动 开发 服务 器 ， 访 问 http://127.0.0.1:8696/search-form/ ， 你 会 看 
到 搜索 界面 。 就 这 么 简单 ! 不过， 提交 表单 时 会 显示 Django 404 错误 。 这 是 因为 表单 指向 的 URL /search/ 
还 未 实现 。 下 面 再 编写 一 个 视图 函数 ， 修 正 这 个 问题 : 


















































大 UPFLSs。.py 


urlpatterns = [ 
村 
url(r'^search-form/$', views.search_form), 
url(r'^search/$', views.search), 
a 
] 


# books/views.py 


from django.http import HttpResponse 


def search(request): 
if 'q' in request.GET: 
message = 'You searched for: %r' % request.GET['g'] 
else: 
message = 'Youy submitted an empty form.' 
return HttpResponse(message) 


目前 ， 这 个 视图 只 是 显示 用 户 搜索 的 词 。 由 此 ， 我 们 可 以 确认 数据 正确 提交 给 Django 了 ， 也 可 以 了 解 搜 索 的 
词 是 如 何在 系统 中 传递 的 。 简 单 来 说 : 







































































1. HTML 表单 定义 一 个 变量 q。 提 交 表 单 后 ，q 的 值 通过 GET 请 求 (method="get") 传 给 /search/。 
2. 处 理 /search/ 的 Django 视图 (search()) 通过 request.GET 访问 q 的 值 。 




















特别 注意 ， 我 们 明确 检查 了 request.GET 中 有 没有 'q' 。6.1.2 市 说 过 ， 不 应 该 相信 用 户 提 交 的 任何 数据 ， 其 
至 可 以 假设 用 户 根本 没有 提交 任何 数据 。 如 果 不 做 这 一 项 检查 ， 提 交 空 表单 会 导致 视图 抛 出 KeyError: 





























# 不 好 

def bad_ search(request): 
# 如 果 未 提交 'q' ， 下 一 行 抛 出 KeyError 
message = 'You searched for: %r' % request.GET['q'] 
return HttpResponse(message) 


6.2.1 查询 字符 串 参 数 


GET 数据 通过 查询 字符 串 传 递 〈 例 如 /search/?q=django) ， 因 此 可 以 使 用 request.GET 获取 查询 字符 串 参 
数 。 第 2 章 介 绍 Django 的 URL 配置 系统 时 ， 我 比较 了 Django 的 精美 URL 和 传统 的 PHP/Java URL， 如 
/time/plus?hours=3， 我 说 我 会 在 第 6 章 说 明 怎 么 得 到 后 一 种 URL。 现 在 你 知道 如 何在 视图 中 访问 查询 字符 
串 参 数 了 (如 这 里 的 hours=3) ， 即 使 用 request.GET。 












































POST 数据 的 访问 方式 与 GET 数据 类 似 ， 只 需 把 request.GET 换 成 request.P0ST。 那 么 ，GET 和 POST 之 间 有 什 
么 区 别 呢 ? 如 果 提 交 表 单 只 是 为 了 “获取 ”数据 ， 使 用 GET。 如 果 提 交 表 单 有 副作用 ， 例 如 修改 数据 、 发 送 电 
子 邮 件 ， 或 者 是 显示 数据 之 外 的 操作 ， 使 用 P0ST。 在 这 个 搜索 图 书 的 示例 中 ， 我 们 使 用 的 是 GET， 因 为 搜索 
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操作 没有 修改 服务 器 中 的 任何 数据 。 (如 果 想 进一步 了 解 GET 和 POST， 请 访问 w3.org 网 站 。) 现在 ， 我 们 已 
经 确认 request.GET 能 正确 传 进来 了 ， 下 面 在 图 书 数据 库 中 执行 用 户 提交 的 搜索 查询 (还 是 在 views.py 文件 









































中 ) : 


from django.http import HttpResponse 
from django.shortcuts import render 
from books.models import Book 


def search(request): 

if 'q' in request.GET and request.GET['q']: 
q = request.GET['g'] 
books = Book.objects.filter(title icontains=q) 
return render(request, 'search _ results.html', 

{'books': books, 'query': q}) 

else: 

return HttpResponse('Please submit a search term.') 


在 这 段 代 码 中 ， 有 几 处 要 注意 : 
。 除了 检查 request.GET 中 有 没有 'q' 之 外 ， 我 们 还 确保 request.GET['q' ] 不 是 空 值 ， 然 后 再 把 查询 传 
给 数据 库 。 
。 我 们 使 用 Book.objects.fiLter(titLe_icontains=q) 在 图 书 表 中 查找 所 有 书 名 中 包含 查询 词 条 的 书 。 


icontains 是 一 种 查找 类 型 (参见 第 4 竟 和 附录 B) ， 这 个 语句 基本 上 相当 于 “获取 所 有 书 名 中 包含 q 
的 书 ， 而 且 不 区 分 大 小 写 ”。 















































这 种 搜索 方式 十 分 简单 。 不 建议 在 大 型 生产 数据 库 中 使 用 icontains 查询 ， 因 为 速度 可 能 很 慢 。 (在 实际 运 
用 中 ， 你 可 能 想 使 用 某 种 自 定 义 的 搜索 系统 。 你 可 以 搜索 一 下 开源 的 全 文 搜索 引擎 。 ) 

















我 们 把 一 组 Book 对 象 books 传 给 模板 。search_results.html 文件 可 以 像 这 样 编写 : 





<htmL> 
<head> 
<title>Book Search</title> 
</head> 
<body> 
<p>You searched for: <strong>{{ query }}</strong></p> 


{% if books %} 
<p>Found {{ books|length }} book{{ books|pluralize }}.</p> 
<ul> 
{% for book in books %} 
<li>{{ book.title }}</\li> 
{% endfor %} 
</ul> 
{% else %} 
<p>No books matched your search criteria.</p> 
{% endif %} 
</body> 
</html> 

















注意 ， 这 里 用 到 了 pluralize 模板 过 滤器 ， 它 会 根据 找到 的 图 书 数量 输出 正确 的 单 复 数 。 




















6.2 一 个 简单 的 表单 处 理 示例 - 
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6.3 改进 这 个 简单 的 表单 处 理 示 例 
































与 前 面 几 章 一 样 ， 我 展示 的 是 最 简 可 用 的 方法 。 现 在 ， 我 要 指出 一 些 问题 ， 并 说 明 如 何 改进 。 首 先 ， 
search() 视图 对 空 查询 的 处 理 不 完美 ， 我 们 只 是 显示 “Please submit a search term.” 消 息 ， 用 户 必 须 点 击 浏览 器 
的 后 退 按钮 。 


这 样 做 不 友好 ， 而 且 显得 不 专业 ， 这 样 的 实现 会 再 次 经 由 Django 处 理 。 遇 到 这 种 情况 时 ， 重 新 显示 表单 ， 并 






































且 在 上 部 显示 错误 更 好 ， 这 样 用户 可 以 立即 再 试 一次。 为 此 ， 最 简单 的 方法 是 再 次 演 染 模板 ， 如 下 所 示 : 


一 、 


空 时 再 次 渔 染 search_form.html 模板 。 因 为 需要 在 模板 中 显示 错误 消息 ， 所 以 我 们 还 传人 了 一 个 模板 变量 。 


> 
六 


from django.http import HttpResponse 
from django.shortcuts import render 
from books.models import Book 


def search_form(request): 
return render(request, 'search form.html') 


def search(request): 
if 'q' in request.GET and request.GET['qg']: 
q = request.GET['qg'] 
books = Book.objects.filter(title_ icontains=q) 
return render(request, 'search_resuLts.htmL ' ， 
{'books': books, 'query': q}) 
else: 
return render(request, 'search form.html', 
{'error': True}) 











FE 意 ， 我 还 列 出 了 search_form()， 以 便 让 你 对 比 两 个 视图 。) 我 们 改进 了 search() 视图 ， 在 查询 词 条 为 




















现在 ， 我 们 可 以 编辑 search_form.htmL， 检 查 error 变量 


<htmL> 
<head> 
<title>Search</title> 
</head> 
<body> 
{% if error %} 
<p style="color: red;">Please submit a search term.</p> 
{% endif %} 
<form action="/search/" method="get"> 
<input type="text" name="q"> 
<input type="submit" value="Search"> 
</form> 
</body> 
</html> 


我 们 可 以 继续 使 用 search_form() 视图 ， 因 为 它 没有 把 error 变量 传 给 模板 ， 所 以 不 会 显示 错误 消息 。 这 样 
修改 之 后 ， 我 们 的 应 用 程序 变 得 更 好 了 ， 但 是 我 们 不 禁 要 问 : 真 的 有 必要 专门 编写 一 个 search_form() 视图 
吗 ? 


按照 现在 的 处 理 方式 ， 对 /search/ 的 请 求 (没有 GET 参数 



































显示 空 的 表单 (没有 错误 ) 。 只 要 我 们 修改 





) 会 3 
search() 视图 ， 在 直接 访问 /search/ 时 (没有 GET 参数 ) 隐藏 错误 消息 ， 就 可 以 把 search_form() 视图 及 对 
应 的 URL 模式 删除 : 
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def search(request ) : 
error = False 
if 'q' in request.GET: 
q = request.GET['q'] 
if not q: 
error = True 
else: 
books = Book.objects.filter(title_ icontains=q) 
return render(request, 'search_resuLts.htmL ' ， 
{'books': books, 'query': q}) 
return render(request, 'search form.html', 
{'error': error}) 














这 样 修改 之 后 ， 当 用 户 直接 访问 /search/ 时 ， 看 到 的 是 没有 错误 的 搜索 表单 ， 如 果 用 户 提交 'q' 为 空 值 的 表 
单 ， 看 到 的 是 带 有 错误 消息 的 搜索 表单 ， 如 果 用 户 提交 'q' 不 为 空 值 的 表单 ， 看 到 的 是 搜索 结果 。 


最 后 ， 我 们 要 删除 一 些 重复 代码 。 现 在 ， 我 们 把 两 个 视图 和 URL 合并 为 一 个 了 ，/search/ URL 既 能 显示 搜 
索 表单 ， 也 能 显示 搜索 结果 ， 那 么 search_form.html 中 的 HTML <form> 不 再 需要 硬 编码 URL 了 。 我 们 要 把 
























































<form action="/search/" method="get"> 


改 为 


nn 


<form action="" method="get"> 








action="" 的 意思 是 ,“ 把 表单 提交 到 与 当前 页 面相 同 的 URL”*。 这 样 修改 之 后 ， 如 果 想 把 search() 视图 放 到 
别 的 URL 上 ， 不 用 再 修改 action 属性 。 




















6.4 简单 的 验证 


这 个 搜索 示例 还 相当 简单 ， 尤 其 是 在 数据 验证 方面 。 我 们 只 是 检查 搜索 词 条 是 否 为 空 。 很 多 HTML 表单 采用 
的 验证 措施 比 确认 值 不 为 空 复杂 得 多 。 我 们 经 常 在 网 站 中 见 到 这 样 的 错误 消息 : 
































“。“ 请 输入 有 效 的 电子 邮件 地 址 。'foo' 不 是 电子 邮件 地 址 。” 
“。“ 请 输入 有 效 的 五 位 数 美国 邮编 。'123' 不 是 邮编 。” 

。“ 请 输入 有 效 的 日 期 ， 格 式 为 YYYY-MM-DD。” 

““ 请 输入 至 少 有 8 个 字符 的 密码 ， 而 且 至 少 有 一 个 数字 。” 




























































































下 面 我 们 来 调整 一 下 search() 视图 ， 让 它 验 证 搜索 词 条 的 长 度 ， 确 保 小 于 或 等 于 20 个 字符 。 (对 这 个 示例 
来 说 ， 我 们 假设 超过 这 一 限制 的 词 条 搜索 起 来 太 慢 。) 但 是 怎么 实现 呢 ? 


最 简单 的 做 法 可 能 是 直接 在 视图 中 实现 相关 逻辑 ， 如 下 所 示 : 


























def search(request ) : 
error = False 
if 'q' in request.GET: 
q = request.GET['q'] 
if not q: 
error = True 
elif len(q) > 20: 
error = True 
else: 
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books = Book.objects.filter(title icontains=q) 
return render(request, 'search_resuLts.htmL ' ， 
{'books': books, 'query': q}) 
return render(request, 'search form.html', 
{'error': error}) 





现在 ， 如 果 搜 索 词 条 超过 20 个 字符 ， 无 法 搜索 ， 你 会 看 到 一 个 错误 消息 。 但 是 ，search_form.html 模板 目前 
显示 的 错误 消息 是 “Please submit a search term.”， 因 此 我 们 要 做 修改 ， 在 两 种 情况 下 显示 不 同 的 消息 : 





<htmL> 
<head> 
<title>Search</title> 
</head> 
<body> 
{% if error %} 
<p style="color: red;"> 
Please submit a search term 20 characters or shorter. 
< /ps 
{% endif %} 


<form action="" method="get"> 
<input type="text" name="q"> 
<input type="submit" value="Search"> 
</form> 
</body> 
</html> 





但 是 ， 现 在 还 有 问题 ， 所 有 错误 都 显示 同一 个 错误 消息 ， 让 人 不 解 。 为 什么 提交 空 值 时 显示 的 错误 消息 要 提 
到 20 个 字符 限制 呢 ? 


错误 消息 应 该 具体 、 无 歧义 、 易 于 理解 。 问 题 的 根源 是 ， 我 们 把 error 变量 的 值 设 成 了 布尔 值 ， 其 实 应 该 设 
为 一 个 错误 消息 字符 串 列 表 。 修 正 的 方法 如 下 : 























def search(request): 
errors = [] 
if 'q' in request.GET: 
q = request.GET['q'] 
if not q: 
errors.append('Enter a search term.') 
elif len(q) > 20: 
errors.append('PLease enter at most 20 characters.') 
else: 
books = Book.objects.filter(title_ icontains=q) 
return render(request, 'search_resuLts.htmL ' ， 
{'books': books, 'query': q}) 
return render(request, 'search form.html', 
{'errors': errors}) 


然后 ， 还 要 稍微 修改 一 下 search_form.html 模板 ， 把 布尔 值 error 改 成 列表 : 


<html> 

<head> 
<title>Search</title> 

</head> 
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<body> 
{% if errors %} 
<ul> 
{% for error in errors %} 
<li>{{ error }}</li> 
{% endfor %} 
</ul> 
{% endif %} 
<form action="" method="get"> 
<input type="text" name="q"> 
<input type="submit" value="Search"> 
</form> 
</body> 
</html> 


6.5 创建 一 个 联系 表单 


虽然 我 们 不 断 改进 图 书 搜索 表单 ， 但 是 它 的 功能 依旧 
每 个 表单 字段 。 在 这 个 过 程 中 容易 引入 大 量 混乱 ， 而 且 人 为 出 错 的 可 能 性 很 大 。 幸 
这 一 点 ， 在 Django 中 内 建 了 高 层级 的 库 ， 能 够 处 理 表单 和 验证 相关 的 任 


们 要 重复 上 述 步 又 ， 处 至 
运 的 是 ，Diango 的 开发 者 想到 了 3 


务 。 


6.5 

















.1 第 一 个 表单 类 




















很 简单 ， 只 有 一 个 字段 ,RR 
























































1 'q' 。 表 单 变 复 杂 之 后 ， 我 


Django 自 带 了 一 个 表单 库 ，django.forms， 它 能 处 理 本 章 所 述 的 多 数 问题 ， 从 显示 HTML 表单 到 验证 ， 都 能 


胜 人 有 








FE。 下 面 我 们 使 用 这 个 Django 表单 框架 为 应 用 程序 构建 一 个 联系 表单 。 





这 个 


这 段 代 码 易于 理解 ， 而 


















































from django import forms 


class ContactForm(forms .Form) : 
subject = forms.CharField() 
email = forms.EmailField(required=False) 
message = forms.CharField() 























表单 框架 的 主要 用 法 是 为 要 处 理 的 每 个 HTML 表单 定义 


























个 Form 类 。 这 里 只 有 一 个 表单 ， 因 出 
义 一 个 Form 类 。 这 个 类 可 以 放 在 任意 位 置 ， 例 如 直接 放 在 views.py 文件 中 ， 不 过 社区 的 约定 是 ， 把 Form 类 
放 在 单独 的 forms.py 文件 中 。 


在 views.py 文件 所 在 的 目录 (mysite) 中 创建 这 个 文件 ， 然 后 输入 下 述 内 容 : 








到 了 CharField 和 EmailField) ,定义 为 Forn 类 的 属性 。 字 段 默认 是 必 填 的 ， 
我 们 指定 了 required=False。 下 面 我 们 在 Python 交互 式 解 释 器 中 看 看 这 个 类 能 做 什么 。 首 先 ， 它 能 
示 为 HTML : 


>>> from mysite.forms import ContactForm 
>>> f = ContactForm() 
>>> print(f) 








日 与 Django 模型 的 句法 相似 。 表 单 中 的 各 个 字段 使 用 相应 的 Field 类 表示 (这 里 只 


只 需 定 





用 


因此 为 了 把 email 设 为 选 填 ， 





<tr><th><label for="id_subject">Subject:</label></th><td><input type="text" name="sub\ 
ject" id="id_subject" /></td></tr><tr><th><label for="id_ email">Email:</label></th><t\ 
d><input type="text" name="email" id="id_ email" /></td></tr><tr><th><label for="id_me\ 
ssage">Message:</label></th><td><input type="text" name="message" id="id message" /><\ 


把 





自己 


项 
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/td></tr> 








为 了 可 访问 性 ，Django 会 为 各 个 字段 添加 标注 (<label> 标签 ) 。Django 会 尽力 把 默认 行为 做 到 最 好 。 上 默认 
的 输出 使 用 HTML 表格 ， 不 过 还 有 几 个 其 他 的 内 置 输出 格式 : 


























>>> print(f.as_ul()) 

<li><label for="id_subject">Subject:</label> 

<input type="text" name="subject" id="id_subject" /></\li><li><label for="id_email">Em\ 
ail:</label> <input type="text" name="email" id="id email" /></li><li><label for="id \ 
message">Message:</label><input type="text" name="message" id="id message"/></\li> 


>>> print(f.as_p()) 

<p><label for="id_subject">Subject:</label><input type="text" name="subject" id="id_s\ 
ubject"/></p><p><label for="id email">Email:</label> <input type="text" name="email" \ 
id="id email" /></p><p><label for="id_message">Message:</label><input type="text" nam\ 
e="message" id="id message"/></p> 





注意 ， 输 出 中 没有 <table>、<ul> 和 <form> 起 始 和 结束 标签 ， 所 以 你 可 以 根据 需要 添加 字段 ， 或 者 做 其 他 定 
制 。 以 上 是 显示 整个 表单 的 方式 ， 此 外 还 可 以 只 显示 某 个 字段 的 HIML: 























>>> print(f['subject']) 

<input id="id_subject" name="subject" type="text" /> 
>>> print f['message'] 

<input id="id_message" name="message" type="text" /> 


Form 对 象 能 做 的 第 二 件 事 是 验证 数据 。 为 此 ， 创 建 一 个 Form 对 象 ， 传 人 一 个 数据 字典 ， 把 字段 名 映射 到 数 
据 上 : 





>>> f = ContactForm({'subject': 'Hello', 'email': 'adrian@Qexample.com', 'message': 'Nice 
site!'}) 








册 


为 Form 实例 关联 数据 后 ， 得 到 了 一 个 “ 受 约束 的 "表单 : 





>>> f.is_bound 
True 





然后 ， 在 受 约束 的 表单 对 象 上 调用 is_valid() 方法 ， 检 查 数据 是 否 有 效 。 前 面 为 各 个 字段 传人 的 值 都 是 有 效 
的 ， 因 此 这 个 表单 对 象 是 完全 有 效 的 : 





>>> f.is_valid() 
True 


如 果 不 传 人 email 字段 ， 仍 然 是 有 效 的 ， 因 为 我 们 为 那个 字段 指定 了 required=False: 


>>> f = ContactForm({'subject': 'Hello', 'message': 'Nice site!'}) 
>>> f.is_valid() 
True 





但 是 ， 如 果 不 提供 subject 或 message 字段 ， 表 单 对 象 就 变 成 无 效 的 了 : 





>>> f = ContactForm({'subject': 'Hello'}) 

>>> f.is_valid() 

False 

>>> f = ContactForm({'subject': 'Hello', 'message': ''}) 
>>> f.is_valid() 
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False 
我 们 可 以 深入 查看 各 个 字段 的 错误 消息 : 


>>> f = ContactForm({'subject': 'Hello', 'message': ''}) 
>>> f['message'].errors 

['This field is required.'] 

>>> f['subject'].errors 

[] 

>>> f['email'].errors 


[] 








每 个 受 约束 的 表单 实例 都 有 一 个 errors 属性 ， 它 的 值 是 一 个 字典 ， 把 字段 名 称 映 射 到 错误 消息 列表 上 : 


>>> f = ContactForm({'subject': 'Hello', 'message': ''}) 
>>> f.errors 
{'message': ['This field is required.']} 














最 后 ， 具 有 有 效 数据 的 表单 实例 有 个 cleaned_data 属性 ， 它 的 值 是 一 个 字典 ， 存 储 着 “清理 后 的 ”提交 数据 。 
Django 的 表单 框架 不 仅 验证 数据 ， 还 会 清理 数据 ， 把 值 转换 成 合适 的 Python 类 型 : 





























>>> f = ContactForm({'subject': 'Hello', 'email': 'adrian@Qexample.com', 
'message': 'Nice site!'}) 

>>> f.is_valid() True 

>>> f.cleaned_data 

{'message': 'Nice site!', 'email': 'adrian@Qexample.com', 'subject': 
'Hello'} 




















这 个 联系 表单 只 处 理 字 符 串 ， 经 “清理 ”后 得 到 字符 串 对 和 象 。 人 然而， 如 果 使 用 IntegerFietLd 或 DateFieLd， 表 
单 框架 会 确保 清理 后 的 数据 使 用 正确 的 Python 整数 或 datetime.date 对 象 。 
































6.6 在 视图 中 使 用 表单 对 象 

















如 果 不 向 用 户 显示 ， 这 个 联系 表单 没有 什么 用 。 为 此 ， 首 先 要 更 新 mysite/views: 





# views.py 


from django.shortcuts import render 

from mysite.forms import ContactForm 

from django.http import HttpResponseRedirect 
from django.core.mail import send_mail 


def contact(request): 
if request.method == 'POST': 
form = ContactForm(request.POST) 
if form.is_valid(): 
cd = form.cleaned_data 
send_mail( 
cd[ 'subject'], 
cd[ 'message ' ] ， 
cd.get('email', 'noreply@example.com'), 
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['siteowner@example.com'], 
) 
return HttpResponseRedirect('/contact/thanks/') 
else: 
form = ContactForm() 
return render(request, 'contact form.html', {'form': form}) 











[了 u 


接 下 来 ， 要 创建 联系 表单 (保存 在 mysite/templates 文件 夹 里 ) : 


# contact_form.html 


<html> 
<head> 
<title>Contact us</title> 
</head> 
<body> 
<h1>Contact Us</h1> 


{% if form.errors %} 
<p style="color: red; "> 
PLease correct the error{{ form.errors|pLuraLize }} below. 
</p> 
{% endif %} 


<form action="" method="post"> 
<table> 
{{ form.as_table }} 
</table> 


{% csrf_token %} 
<input type="submit" value="Submit"> 
</form> 
</body> 
</html> 











最 后 ， 要 修改 urls.py 文件 ， 在 /contact/ URL 上 显示 联系 表单 : 


此 





类 


from mysite.views import hello, current_ datetime, hours_ahead, contact 


urlpatterns = [ 


url(r'^contact/$', contact), 


] 








这 个 表单 使 用 PoST 处 理 (要 修改 数据 ) ， 因 此 要 关心 跨 站 请 求 伪 造 (Cross Site Request Forgery，CSRF) 。 
幸好 ， 我 们 无 需 太 过 担心 ， 因 为 Django 提供 了 非常 易 用 的 防护 系统 。 简 单 来 说 ， 所 有 通过 POST 指向 内 部 
URL 的 表单 都 应 该 使 用 { csrf_token %} 模板 标签 。 关 于 这 个 标签 的 详情 ， 参 见 第 19 章 。 




















在 本 地 运行 一 下 这 个 表单 ， 不 填写 任何 字段 、 填 写 无 效 的 电子 邮件 地 址 ， 再 填写 有 效 的 数据 ， 分 别提 交 试 一 
下 。 (当然 ， 如 果 没 有 配置 邮件 服务 器 ， 调 用 send_mail() 时 会 抛 出 ConnectionRefusedError。) 
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6.7 改变 字段 的 泻 染 方式 





在 本 地 浑 染 这 个 表单 后 ， 你 注意 到 的 第 一 件 事 可 能 是 message 字段 显示 为 <input type="text">， 而 它 应 该 为 
<textarea>。 这 个 问题 可 以 通过 设 定 字段 的 widget 参数 修正 : 











from django import forms 


class ContactForm(forms .Form) : 
subject = forms.CharField() 
email = forms.EmailField(required=False) 
message = forms.CharField(widget=forms.Textarea) 














表单 框架 把 各 个 字段 的 表现 逻辑 交 给 widget 参数 负责 。 每 种 字段 的 widget 参数 都 有 默认 值 ， 不 过 可 以 轻易 
覆盖 ， 或 者 自 定 义 。FietLd 类 表示 验证 逻辑 ， 而 widget 表示 表现 逻辑 。 



































6.8 设 定 最 大 长 度 





最 常见 的 验证 需求 是 检查 字段 中 的 值 是 否 为 特定 的 长 度 。 保 险 起 见 ， 我 们 应 该 改进 ContactForm， 限 制 sub- 
ject 的 值 在 100 个 字符 以 内 。 为 此 ， 只 需 为 charField 指定 max_length 参数 ， 如 下 所 示 : 


from django import forms 


class ContactForm(forms .Form) : 
subject = forms.CharField(max_length=100) 
email = forms.EmailField(required=False) 
message = forms.CharField(widget=forms.Textarea) 


此 外 ， 还 有 个 mn_Length 参数 。 


6.9 设 定 初始 值 








下 面 继续 改进 这 个 表单 ， 为 subject 字段 添加 一 个 初始 值 :“Ilove your site!” (提供 一 些 建议 总 是 好 的 。) 为 
此 ， 创 建 Form 实例 时 可 以 提供 initial 参数 : 





def contact(request): 
if request.method == "POST ': 
form = ContactForm(request.POST) 
if form.is_valid(): 
cd = form.cleaned_data 
send_mail( 
cd['subject'], 
cd[ 'message'], 
cd.get('email', 'noreply@example.com'), 
['siteowner@example.com'], 
) 
return HttpResponseRedirect('/contact/thanks/') 
else: 
form = ContactForm( 
initial={'subject': 'I Love your site!'} 
) 


return render(request, 'contact form.html', {'form':form}) 
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现在 ，subject 字段 中 会 显示 一 句 赞扬 的 话 。 注 意 ， 传 递 初始 值 与 传递 绑 定 表单 的 数据 不 同 ， 二 者 之 间 最 大 
的 区 别 是 ， 传 递 初始 数据 时 ， 表 单 不 受 约束 ， 因 此 不 会 产生 任何 错误 消息 。 








6.10 自 定义 验证 规则 














mm 





假如 我 们 推出 了 反馈 表单 ， 电 子 邮 件 纷 至 坦 来 。 这 就 引出 一 个 问题 : 有 些 邮 件 可 能 只 有 一 两 个 词 ， 不 知 所 
云 。 因 此 ， 我 们 决定 采取 一 个 新 的 验证 措施 : 建议 写 四 个 词 以 上 。 


在 Django 表单 中 使 用 自 定义 的 验证 有 多 种 方式 。 如 果 验 证 规则 要 不 断 复 用 ， 可 以 自 定义 一 个 字段 类 型 。 不 
过 ， 多 数 定义 的 验证 都 是 一 次 性 的 ， 可 以 直接 写 在 Form 类 中 。 我 们 想 对 message 字段 做 额外 的 验证 ， 因此 
在 Form 类 中 添加 一 个 clean_message() 方法 : 


















































from django import forms 


class ContactForm(forms.Form): 
subject = forms.CharField(max_length=100) 
email = forms.EmailField(required=False) 
message = forms.CharField(widget=forms.Textarea) 


def clean_message(self): 
message = self.cleaned data[ 'message'] 
num words = len(message.split()) 
if num_words < 4: 
raise forms.ValidationError("Not enough words!") 
return message 














Django 的 表单 系统 会 自动 查找 名 称 以 clean_ 开头 、 以 字段 名 结尾 的 方法 。 如 果 存 在 这 样 的 方法 ， 在 验证 过 
程 中 调用 。 这 里 ，clean_message() 方法 会 在 指定 字段 的 默认 验证 逻辑 (这 个 charField 是 必 填 的 ) 执行 完毕 
后 调用 。 


因为 字段 数据 经 过 部 分 处 理 了 ， 所 以 从 self.cleaned_data 中 获取 。 此 外 ， 我 们 无 需 检 查 值 是 否 存 在 ， 或 者 
不 为 空 ， 默 认 的 验证 逻辑 已 经 检查 过 了 。 我 们 的 处 理 方式 很 简单 ， 只 是 使 用 len() 和 sptLit() 计算 单词 的 数 
量 。 如 果 用 户 输入 的 词 数 过 少 ， 抛 出 forms.ValidationError。 










































































这 个 异常 中 指定 的 字符 串 会 出 现在 错误 消息 列表 中 显示 给 用 户 。 注 意 ， 方 法 的 最 后 一 定 要 显 式 返回 那个 字段 
清理 后 的 值 。 这 样 才能 在 自 定义 的 验证 方法 中 修改 那个 值 (或 者 转换 成 其 他 Python 类 型 ) 。 如 果 没 有 return 
语句 ， 返 回 的 是 None， 如 此 一 来 原来 的 值 就 丢失 了 。 
































6.11 指定 标注 





在 Django 自动 生成 的 表单 HTML 中 ， 默 认 的 标注 是 把 下 划 线 替换 成 空格 ， 并 把 首 字母 变 成 大 写 ， 例 如 ， 
email 字段 的 标注 是 "Email"。 ( 听 着 很 熟悉 吧 ， 这 与 Django 的 模型 为 字段 生成 verbose_name 的 值 使 用 的 算 
法 相同 。 我 们 在 第 4 章 介 绍 过 。) 与 Django 的 模型 一 样 ， 字 段 的 标注 是 可 以 自 定义 的 。 方 法 很 简单 ， 指 定 
label 参数 即 可 ， 如 下 所 示 : 














class ContactForm(Cforms .Form) : 
subject = forms.CharField(max_length=100) 
email = forms.EmailField(required=False, label='Your e-mail address ') 
message = forms.CharField(widget=forms.Textarea) 
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6.12 自 定义 表单 的 外 观 














contact_form.html 模板 使 
控制 外 观 。 自 定义 表征 


错误 列表 尤其 可 以 做 些 外 观 上 的 改进 。 
































] {{ form.as_table }} 显示 表 自 
有 外观 最 简便 的 方法 是 使 用 CSS。 


自动 4 


ve 


通过 





外 削 














， 不 过 我 们 可 以 他 方式 显示 表单 ， 进 一 步 

















Fs 





E 成 的 错误 列表 使 用 <ul class="errorlist">， 因 此 可 以 使 用 





CSS 美化 。 下 述 CSS 把 错误 列表 突出 显示 


<style type="text/css"> 
ulaertorlist { 
gin: 0; 





.errorlist LiL { 


or: red; 


Sp eg 
groungd -COL 





white; 








y: block; 
ize: 10px; 
hn: 0 © 3px: 
: 4px 5px; 
} 
</style> 














虽然 可 以 让 Django 为 我 们 生成 表 六 





的 HTML,， 但 是 很 


来 ; 




















多 时 候 我 们 并 不 想 用 默认 的 泻 染 方式 。{{ 














form.as_table }} 等 是 有 用 的 快捷 方式 ， 在 
定制 的 ， 而 且 大 多 数 时 


在 模板 中 ， 每 个 字段 使 用 的 控件 (<input t 
form.fieldname }} 单独 演 染 ， 























了 人 解 这 些 之 后 ， 我 们 可 以 使 用 下 述 代码 自 定义 联系 表 入 


<htmL> 
<head> 
<title>Contact us</title> 
</head> 
<body> 
<h1>Contact Us</h1> 


{% if form.errors %} 
<p style="color: red;"> 


侯 都 在 模板 中 一 一 你 肯定 会 





开发 应 用 程序 的 过 程 中 能 节省 时 间 ， 但 是 表单 的 显示 方式 是 可 以 
这 么 做 的 。 





等 


等 等 ) 可 以 使 用 {{ 


ype= "text">、<SeLect>、<textarea>， 





而 各 个 字段 上 的 错误 可 以 通过 {{ form.fieldname.errors }} 获取 。 

















的 模板 : 





Please correct the error{{ form.errors|pluralize }} below. 


</p> 
{% endif %} 


<form action="" method="post"> 
<div class="field"> 


{{ form.subject.errors }} 
<label for="id_ subject">Subject:</label> 


{{ form.subject }} 
</div> 
<div class="field"> 

{{ form.email.errors }} 
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<label for="id email">Your e-mail address:</label> 
{{ form.email }} 
</div> 
<div class="field"> 
{{ form.message.errors }} 
<label for="id message">Message:</label> 
{{ form.message }} 
</div> 
{% csrf_token %} 
<input type="submit" value="Submit"> 
</form> 
</body> 
</html> 





错误 时 ，{{ form.message.errors }} 显示 一 个 <ul class="errorlist"> 元 素 ; 字段 有 效 时 (或 者 表单 未 受 
约束 时 ) ， 显 示 一 个 空白 字符 串 。 我 们 可 以 把 form.message.errors 视 作 布尔 值 ， 也 可 以 视 作 可 迭代 的 列表 。 
例如 : 




















<div class="field{% if form.message.errors %} errors{% endif %}"> 
{% if form.message.errors %} 
<ul> 
{% for error in form.message.errors %} 
<li><strong>{{ error }}</strong></li> 
{% endfor %} 
</ul> 
{% endif %} 
<label for="id message">Message:</label> 
{{ form.message }} 
</div> 





验证 错误 时 ， 上 述 代码 在 <div> 容器 中 添加 errors 类 ， 并 且 在 一 个 无 序列 表 中 显示 错误 。 














6.13 接 下 来 


至 此 ， 本 书 对 基础 知识 (也 叫 “ 核 心 课程 ") 的 介绍 结束 了 。 在 接 下 来 的 一 部 分 ， 即 第 7 章 到 第 13 章 ， 我 们 将 
讨论 更 高 级 的 Django 用 法 ， 例 如 如 何 部 署 Django 应 用 程序 (第 13 章 ) 。 读 完 前 六 章 ， 你 应 该 可 以 着 手 编写 
自己 的 Django 项目 了 。 本 书 剩 下 的 内 容 为 你 提供 补充 知识 。 在 第 7 章 ， 我 们 将 回 过 头 来 深入 探讨 视图 和 
URL 配置 (第 2 章 简 单 介绍 过 ) 。 



























































98 - 第 6 章 Django 表单 





第 7 章 高 级 视图 和 URL 配置 














第 2 章 简单 介绍 了 Django 的 视图 函数 和 URL 配置 ， 本 章 深入 更 多 细节 ， 学 习 这 两 部 分 的 高 级 功能 。 

















7.1 URL 配置 小 技巧 








URL 配置 没什么 特殊 的 ， 与 Django 的 其 他 部 分 一 样 ， 只 不 过 是 普通 的 Python 代码 。 鉴 于 此 ， 我 们 可 以 利用 
一 些 Python 技巧 ， 充 分 发 挥 URL 配置 的 作用 ， 详 情 参 见 接 下 来 的 几 闻 。 
































< 








7.1.1 简化 导入 函数 的 方式 





我 们 来 看 一 下 第 2 章 中 的 一 个 URL 配置 





from django.conf.urls import include, url 
from django.contrib import admin 
from mysite.views import hello, current_ datetime, hours_ahead 


urlpatterns = [ 
url(r'^admin/', include(admin.site.urls)), 
url(r'^hello/$', hello), 
url(r'^time/$', current_datetime), 
url(r'^time/plus/(\d{1,2})/$', hours_ahead), 
] 


第 2 章 说 过 ，URL 配置 中 的 每 个 条 目 都 有 对 应 的 视 
模块 的 顶部 导入 视图 函数 。 

但 是 ， 随 着 Django 应 用 程序 越 变 越 复杂 ，URL 配置 的 内 容 会 越 变 越 多 ， 一 个 一 个 地 导入 视图 函数 就 显得 繁 
琐 。 (每 个 视图 函数 都 要 导入 ， 导 入 语句 会 变 得 越 来 越 长 。) 








函数 ， 通 过 函数 对 象 直接 传人 。 因 此 ， 要 在 URL 配置 


LA 
























































为 了 避免 这 种 麻烦 ， 我 们 可 以 导入 views 模块 自身 。 下 述 URL 配置 与 前 面 的 效果 一 样 : 














from django.conf.urls import include, url 
from . import views 


urlpatterns = [ 
url(r'^hello/$', views.hello), 
url(r'^time/$', views.current_datetinme), 
url(r'^time/plus/(d{1,2})/$', views.hours_ahead), 


7.1.2 在 调试 模式 下 提供 特殊 的 URL 





说 到 动态 构建 urlpatterns， 你 可 能 想 利 用 这 个 技巧 在 Django 的 调试 模式 下 调整 URL 配置 的 行为 。 为 此 ， 只 





需 在 运行 时 检查 DEBUG 设置 ， 如 下 所 示 : 





from django.conf import settings 
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from django.conf.urls import url 
from . import views 


urlpatterns = [ 
url(r'^$', views.homepage), 
url(Cr'^(\d{4})/([a-z]{3})/$', views.archive month), 
] 


if settings.DEBUG: 
urlpatterns += [url(r'^debuginfo/$', views.debug),] 


这 里 ， 仅 当 DEBUG 的 值 为 True 时 ，/debuginfo/ URL 才 可 以 访问 。 


7.1.3 具名 分 组 


上 述 示例 没有 使 用 具名 的 正则 表达 式 分 组 (通过 括号 实现 ) 捕获 URL 中 的 片段 ， 而 是 通过 位 置 参数 把 片段 传 
给 视图 。 
在 高 级 用 法 中 ， 可 以 使 用 具名 的 正则 表达 式 分 组 捕获 URL 片段 ， 通 过 关键 字 参 数 把 片段 传 给 视 














本 


















































在 Python 正则 表达 式 中 ， 具 名 分 组 的 句法 是 (?P<name>pattern)， 其 中 name 是 分 组 的 名 称 ，pattern 是 要 匹 
配 的 模式 。 
假如 我 们 的 图 书 网 站 中 有 一 些 书 评 ， 而 我 们 想 检 索 特 定 日 期 或 日 期 范围 内 的 书评 。 









































下 面 是 URL 配置 





from django.conf.urls import url 
from . import views 


urlpatterns = [ 
url(r'^reviews/2003/$', views.special_case 2003), 
url(r'^reviews/([0-9]{4})/$', views.year_archive), 
url(r'^reviews/([0-9]{4})/([0-9]{2})/$', views.month_archive), 
url(r'^reviews/([0-9]{4})/([0-9]{2})/([0-9]+)/$', views.review detail), 


划 
le 


。 若 想 捕获 URL 中 的 值 ， 把 值 放 在 括号 里 。 

。 无 需 使 用 前 导 斜 线 ， 每 个 URL 本 身 就 有 。 例 如 ， 是 ^reviews， 而 非 ^/reviews。 

。 每 个 正则 表达 式 字符 串 前 面 的 'r' 是 可 选 的 ， 但 是 建议 加 上 。 它 的 作用 是 告诉 Python， 那 是 “原始 " 字 
符 串 ， 里 面 的 一 切 内 容 都 不 应 该 转 义 。 






































示例 请 求 : 











。 对 /reviews/2005/03/ 的 请 求 匹 配 上 述 列表 中 的 第 三 个 条 目 。Django 调用 views.month_archive(re- 
quest，'2005' ，'03') 函数 。 

。 /reviews/2995/3/ 不 匹配 任何 URL 模式 ， 因 为 列表 中 的 第 三 个 条 目 要 求 月 份 有 两 个 数字 。 

。 /reviews/2903/ 匹配 列表 中 的 第 一 个 模式 ， 而 不 是 第 二 个 ， 因 为 模式 按 顺序 测试 ， 而 第 一 个 就 能 让 测 
斌 通过。 你 可 以 调整 顺序 ， 添 加 类 似 这 样 的 特例 。 
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。 /reviews/12663 不 匹配 任何 模式 ， 因 为 每 个 模式 都 要 求 URL 的 未 尾 有 一 条 斜 线 。 
。 /reviews/2093/93/93/ 匹配 最 后 一 个 模式 。Django 调用 views .review_detaiL(request，'2003' ，'03 ' ， 
'03' ) 函数 。 




















下 述 URL 配置 与 前 面 的 作用 一 样 ， 不 过 换 用 具名 分 组 了 : 


from django.conf.urls import url 
from . import views 


urlpatterns = [ 
url(r'^reviews/2003/$', views.special_case 2003), 
url(r'^reviews/(?P<year>[0-9]{4})/$', views.year_archive), 
url(r'^reviews/(?P<year>[0-9]{4})/(?P<month>[0-9]1{2})/$', 
views.month_archive), 
url(r'^reviews/(?P<year>[0-9]{4})/(?P<month>[0-9]{2})/(?P<day>[0-9]{2})/$', 
Views.review_detail), 


] 


这 个 URL 配置 与 前 一 个 实现 的 URL 模式 完全 一 样 ， 只 不 过 有 一 处 不 同 : 捕获 的 值 以 关键 字 参 数 传 给 视图 函 
数 ， 而 不 是 位 置 参 数 。 例 如 : 





























。 对 /reviews/2005/03/ 的 请 求 调用 views .month_archive(request,year='2005' ,month='03') 函数 ， 而 不 
是 views.month_archive(request,'2005','03')。 











。 对 /reviews/2093/93/93/ 的 请 求 调用 views.review_detail(re- 
quest,year='2003' ,month='03' ,day='03' ) 国 数 。 
































在 实际 运用 中 ， 这 样 做 的 好 处 是 URL 配置 的 意图 稍微 明显 一 些 ， 而 且 不 容易 出 现 由 于 参数 顺序 不 当 导 致 的 缺 
陷 ， 因 为 视图 函数 定义 中 的 参数 顺序 可 以 调整 。 当 然 ， 这 也 牺牲 了 一 些 简洁 性 ， 有 些 开发 者 觉得 具名 分 组 名 
法 不 美观 ， 而 且 太 喝 嗪 。 















































匹配 /分 组 算法 














URL 配置 解析 器 解析 正则 表达 式 中 具名 分 组 和 非 具 名 分 组 所 采用 的 算法 如 下 : 



























































1. 如 果 有 具名 分 组 ， 使 用 具名 分 组 ， 忽 略 非 具名 分 组 。 
2.， 否则 ， 以 位 置 参 数 传递 所 有 非 具 名 分 组 。 















































不 论 如 何 ， 额 外 的 关键 字 参 数 都 会 传 给 视图 。 











7.1.4 URL 配置 搜索 的 范围 











URL 配置 搜索 的 是 所 请 求 的 URL， 而 且 把 它 视 作 普通 的 Python 字符 串 。 搜 索 的 范围 不 包括 GET 或 P0ST 参 
数 ， 抑 或 域名 。 例 如 对 http://www.example.com/myapp/ 的 请 求 ，URL 配置 只 查找 myapp/; 对 http://www.ex- 
ample.com/myapp/?page=3 的 请 求 ，URL 配置 只 查找 myapp/。URL 配置 不 关心 请 求 方法 。 也 就 是 说 ， 相 同 
URL 的 所 有 请 求 方法 (P0ST、GET、HEAD， 等 等 ) 都 交 由 同一 个 视图 函数 处 理 。 








































































































7.1.5 捕获 的 参数 始终 是 字符 串 


不 管 正则 表达 式 匹 配 的 是 什么 类 型 ， 捕 获 的 每 个 参数 都 以 普通 的 Python 字符 串 传 给 视图 。 对 URL 配置 中 的 
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url(r'^reviews/(?P<year>[0-9]{4})/$', views.year_archive), 





虽然 [9-9]{4} 只 匹配 字符 串 中 的 整数 ， 但 是 传 给 views .year_archive() 视图 函数 的 year 参数 是 字符 串 ， 而 
不 是 整数 。 





7.1.6 为 视图 的 参数 指定 默认 值 


一 个 常用 的 技巧 是 为 视图 的 参数 指定 默认 值 。 以 下 面 的 URL 配置 为 例 : 




















大 URL 配置 
from django.conf.urls import url 
from . import views 


urlpatterns = [ 
UrLCr ^reviews/$ ，Views .page)， 
url(r'^reviews/page(?P<num>[0-9]+)/$', views.page), 


] 


# 视图 (在 reviews/views.py 文件 中 ) 
def page(request, num="1"): 
# 输出 指定 数量 的 书评 














在 上 述 示例 中 ， 两 个 URL 模式 指向 同一 个 视图 ， 即 views .page， 但 是 第 一 个 模式 没有 从 URL 中 匹配 任何 内 
容 。 如 果 匹 配 第 一 个 模式 ，page() 函数 使 用 nun 的 默认 值 ， 即 "1"， 如 果 匹 配 第 二 个 模式 ，page() 函数 使 用 
正则 表达 式 匹配 的 num 值 。 




















7.2 性 能 





urtLpatterns 中 的 每 个 正则 表达 式 在 首次 访问 时 编译 ， 因 此 系统 的 速度 异常 得 快 。 














旁 注 7-1， 关 键 字 参 数 与 位 置 参 数 





























调用 Python 函数 时 可 以 使 用 关键 字 参 数 ， 也 可 以 使 用 位 置 参数 ， 而 且 有 些 时 候 二 者 同时 使 用 。 使 用 关键 
字 参 数 时 ， 参 数 的 名 称 和 值 一 起 传递 ， 使 用 位 置 参数 时 ， 只 传递 值 ， 而 不 明确 指定 哪个 参数 匹配 哪个 
值 ， 二 者 的 关系 由 参数 的 顺序 确定 。 


例如 ， 对 下 面 这 个 简单 的 函数 来 说 : 















































def sell(item, price, quantity): 
print "Selling %s unit(s) of %s at %s" % (quantity, item, price) 

















如 有 果 使 用 位 置 参 数 ， 要 按照 函数 定义 中 指定 的 顺序 传 入 : 











sell( "Soceks’, "$2.50", 6) 

















如 果 使 用 关键 字 参 数 ， 要 把 参数 的 名 称 与 值 一 起 传人 。 下 面 各 个 调用 是 等 价 的 : 























sell(item='Socks', price='$2.50', quantity=6) 
sell(item='Socks', quantity=6, price='$2.50') 
sell(price='$2.50', item='Socks', quantity=6) 
sell(price='$2.50', quantity=6, item='Socks') 
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sell(quantity=6, item="'Socks', price='$2.50') 
sell(quantity=6, price='$2.50', item='Socks') 








最 后 ， 还 可 以 混用 关键 字 参 数 和 位 置 参数 ， 只 要 把 位 置 参 数 放 在 关键 字 参 数 前 面 就 行 。 下 面 各 个 调用 与 
前 面 的 等 价 : 




















sell('Socks', '$2.50', quantity=6) 
sell('Socks', price='$2.50', quantity=6) 
sell('Socks', quantity=6, price='$2.50') 











7.3 错误 处 理 








路 











找 不 到 匹配 所 请 求 URL 的 正则 表达 式 或 有 异常 抛 出 时 ，Django 会 调用 一 个 错误 处 理 视图 。 具 体 使 用 的 视 
由 四 个 参数 指定 。 这 四 个 参数 是 : 








。 handler404 
。 handLer500 
。 handler403 


。 handler400 














对 多 数 项 目 来 说 ， 使 用 默认 的 处 理 视图 应 该 就 够 了 ， 然 而 ， 如 果 想 定制 ， 也 可 以 把 它们 设 为 其 他 值 。 这 四 个 
参数 的 值 在 根 URL 配置 中 设 定 ， 在 其 他 位 置 设 定 无 效 。 设 定 的 值 必须 是 可 调用 的 对 象 ， 或 者 是 表示 完整 的 
Python 导入 路 径 的 字符 串 ， 指 向 处 理 相应 错误 的 视图 。 


























7.4 引入 其 他 URL 配置 





urlpatterns 在 任何 位 置 都 可 以 “引入 ”其 他 URL 配置 模块 。 通 过 这 一 行为 可 以 把 一 些 URL 放 在 另 一 些 名 下 。 
例如 ， 下 面 是 Django 项 目的 网 站 的 URL 配置 ， 从 其 他 位 置 引 入 了 一 些 URL 配置 : 























from django.conf.urls import include, url 


urlpatterns = [ 
和 
url(r'^community/', include('django_website.aggregator .UrlLs ' ) )， 
url(r'^contact/', include('django website.contact.urls')), 
Ws 

] 


注意 ， 这 里 的 正则 表达 式 没有 $ 《匹配 字符 串 来 尾 的 符号 ) ， 但 是 未 尾 有 斜 线 。Django 遇 到 inctude() 时 ， 
会 把 截至 那 一 位 置 匹 配 的 URL 截断 ， 把 余下 的 字符 串 传 给 引入 它 的 URL 配置 ， 做 进一步 处 理 。 此 外 ， 还 可 
以 使 用 urt() 引入 额外 的 URL 模式 。 以 下 述 URL 配置 为 例 : 





















































from django.conf.urls import include, url 
from apps.main import views as main_views 
from credit import views as credit views 


extra_patterns = [ 
url(r'^reports/(?P<id>[0-9]+)/$', credit views.report), 
url(r'^charge/$', credit views.charge), 
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urlpatterns = [ 
url(r'^$', main_views.homepage), 
url(r'^help/', include('apps.help.urls')), 
url(r'^credit/', include(extra_patterns)), 


] 


这 里 ，/credit/reports/ URL 由 credit.views.report() 视图 处 理 。 利 


复 ， 在 多 处 使 用 相同 的 模式 前 级 。 来 看 这 个 URL 配置 





from django.conf.urls import url 
from . import views 


urlpatterns = [ 
url(r'^(?P<page_slug>\w+)-(?P<page_ id>\w+)/history/$', 
views.history), 
url(r'^(?P<page_slug>\w+)-(?P<page_ id>\w+)/edit/$', 
views .edit), 
url(r'^(?P<page_slug>\w+)-(?P<page id>\w+)/discuss/$', 
views.discuss), 


url(r'^(?P<page_slug>\w+)-(?P<page_id>\w+)/permissions/$', 


views.permissions), 


] 






































行为 可 以 去 除 URL 配置 中 的 重 





我 们 可 以 改进 这 个 URL 配置 ， 把 共用 的 路 径 前 绥 提 取出 来 ， 再 把 不 同 的 部 分 放 在 其 后 : 














from django.conf.urls import include, url 
from . import views 


urlpatterns = [ 
url(r'^(?P<page_slug>\w+)-(?P<page_id>\w+)/',， 
include([ 
url(r'^history/$', views.history), 
url(r'^edit/$', views.edit), 
url(r'^discuss/$', views.discuss), 
url(r'^permissions/$', views.permissions), 
]) 
), 


7.4.1 捕获 的 参数 








被 引入 的 URL 配置 会 接收 到 父 级 URL 配置 捕获 的 参数 ， 因 此 下 述 示例 是 有 效 的 : 


# settings/urls/main.py 
from django.conf.urls import include, url 


urlpatterns = [ 


url(r'^(?P<username>\w+)/reviews/', include('foo.urls.reviews')), 


# foo/urls/reviews.py 
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from django.conf.urls import url 
from . import views 


urlpatterns = [ 
url(r'^$', views.reviews.index), 
url(r'^archive/$', views.reviews.archive), 


] 
这 里 ， 捕 获 的 "username" 变量 能 顺利 传 给 被 引入 的 URL 配置 。 





7.5 给 视图 函数 传递 额外 参数 











URL 配置 允许 向 视图 函数 传递 额外 的 参数 ， 这 些 参数 放 在 一 个 Python 字典 中 。django.conf.urls.url() 函数 
的 第 三 个 参数 是 可 选 的 ， 如 果 指 定 ， 应 该 是 一 个 字典 ， 指 定 要 传 给 视图 函数 的 额外 关键 字 参 数 及 其 值 。 例 
如 : 








from django.conf.urls import url 
from . import views 


urlpatterns = [ 
url(r'^reviews/(?P<year>[0-9]{4})/$', 
views .year_archive, 
{'foo': 'bar'} 
)， 
] 


对 这 个 示例 来 说 ， 请 求 /reviews/2005/ 时 ，Django 调用 views.year_archive(request，year='2005 ' ， 
foo='bar')。 聚 合 (syndication) 框架 通过 这 种 方式 把 元 数据 和 选项 传 给 视图 (参见 第 14 章 ) 。 


有 可 能 URL 模式 捕获 了 具名 关键 字 参 数 ， 又 在 第 三 个 参数 中 传递 同名 的 参数 。 此 时 ，Dijango 
使 用 字典 中 的 参数 ， 而 不 是 从 URL 中 捕获 的 参数 。 


7.5.1 给 inctude() 传递 额外 参数 


同样 ， 也 可 以 为 include() 传递 额外 参数 。 此 时 ， 被 引入 的 URL 配置 中 的 每 一 行 都 将 收 到 额外 的 参数 。 例 
如 ， 下 述 两 个 URL 配置 的 作用 是 一 样 的 。 


第 一 个 URL 配置 : 


# main.py 
from django.conf.urls import include, url 


urlpatterns = [ 
url(r'^reviews/', include('inner'), {'reviewid': 3}), 


] 


# inner.py 
from django.conf.urls import url 
from mysite import views 
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urlpatterns = [ 
url(r'^archive/$', views.archive), 
url(r'^about/$', views.about), 


] 


第 二 个 URL 配置 : 








# main.py 
from django.conf.urls import include, url 
from mysite import views 


urlpatterns = [ 
url(r'reviews/', include('inner')), 


] 


# inner.py 
from django.conf.urls import url 


urlpatterns = [ 
url(r'^archive/$', views.archive, {'reviewid': 3}), 
url(r'^about/$', views.about, {'reviewid': 3}), 


] 





注意 ,不管 URL 模式 是 否 能 接收 参数 ， 额 外 的 参数 都 将 传 给 被 引入 的 URL 配置 的 每 个 模式 。 鉴 于 此 ， 仅 当 
角 定 被 引入 的 URL 配置 中 的 每 个 视图 都 接收 传人 的 额外 参数 时 ， 才 应 该 这 么 做 。 








一 























7.6 反 向 解析 URL 


在 Django 项 目 中 经 常 需 要 获取 URL 的 最 终 形 式 ， 这 么 做 是 为 了 在 生成 的 内 容 中 艇 入 URL (视图 和 静态 资源 
的 URL、 呈 现 给 用 户 的 URL， 等 等 ) ， 或 者 在 服务 器 端 处 理 导航 流程 〈 重 定向 等 ) 。 











此 时 ， 一 定 不 能 硬 编码 URL (费时 、 不 可 伸缩 ， 而 且 容 易 出 错 ) ， 或 者 参照 URL 配置 创造 一 种 生成 URL 的 
机 制 ， 因 为 这 样 容易 导致 线 上 URL 失效 。 也 就 是 说 ， 我 们 需要 一 种 不 自我 重复 的 机 制 。 



































这 种 机 制 的 一 个 优点 是 ， 改 进 URL 设计 之 后 无 需 在 项 目的 源码 中 大 范围 搜索 ， 替 换 掉 过 期 的 URL。 目 前 ， 
我 们 能 获取 的 信息 有 负责 处 理 URL 的 视图 标识 〈 即 视图 名 称 ) ， 以 及 查找 正确 URL 所 需 的 视图 参数 类 型 
(位 置 参数 或 关键 字 参 数 ) 和 值 。 













































































Django 提供 了 一 种 方案 ， 只 需 在 URL 映射 中 设计 URL。 我 们 为 其 提供 URL 配置 ， 然 后 可 以 双向 使 用 : 
























































。 从 用 户 〈 浏 览 器 ) 请 求 的 URL 开始 ， 这 个 方案 能 调用 正确 的 Django 视图 ， 并 从 URL 中 提取 可 能 需要 
的 参数 及 其 值 ， 传 给 视图 。 


。 从 Django 视图 对 应 的 标识 以 及 可 能 传 入 的 参数 值 开 始 ， 获 取 相 应 的 URL。 
































第 一 点 就 是 我 们 目前 所 讨论 的 处 理 方式 。 第 二 点 称 为 反 向 解析 URL、 反 向 匹配 URL、 反 向 查找 URL 或 URL 
反 转 。 


Django 在 不 同 的 层 中 提供 了 执行 URL 反 转 所 需 的 工具 : 























。 在 模板 中 ， 使 用 urt 模板 标签 。 
。 在 Python 代码 中 ， 使 用 django.core.urlresolvers.reverse() 困 数 。 
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。 在 处 理 Django 模型 实例 URL 相关 的 高 层 代 码 中 ， 使 用 get_absoLute_urtL() 方法 。 











7.6.1 示例 





仍 以 下 述 URL 配置 为 例 : 


from django.conf.urls import url 
from . import views 


urlpatterns = [ 
Wy 
url(r'^reviews/([0-9]{4})/$', views.year_archive, 
name=' reviews-year-archive'), 


] 


根据 这 个 设计 ，nnnn 年 的 存档 对 应 的 URL 是 /reviews/nnnn/。 在 模板 中 可 以 使 用 下 述 代码 获取 这 个 URL: 





<a href="{% url 'reviews-year-archive' 2012 %}">2012 Archive</a> 


{# 或 者 把 年 份 存储 在 一 个 模板 上 下 文 变量 中 : 内 


<UL> 

{% for yearvar in year_list %} 

<li><a href="{% url 'reviews-year-archive' yearvar %}">{{ 
yearvar }} Archive</a></\i> 

{% endfor %} 

</ul> 





在 Python 代码 中 则 要 这 么 做 : 


from django.core.urlresolvers import reverse 
from django.http import HttpResponseRedirect 


def redirect_ to_year(request): 
a 
year = 2012 
着 
return HttpResponseRedirect(reverse('reviews-year-archive', args=(year,))) 





如 果 基 于 某 些 原因 ， 想 修改 显示 年 份 书评 存档 的 URL， 只 需 修改 URL 配置 中 的 条 目 。 某 








些 情况 下 ， 视 图 是 





通用 的 ，URL 和 视图 之 间 存 在 多 对 一 关系 ，URL 反 转 时 视图 名 称 不 足以 唯一 标识 。Django 为 此 提供 的 解决 





方案 参阅 下 一 节 。 


7.7 为 URL 模式 命名 





为 了 执行 URL 反 转 ， 要 像 前 述 示 例 那样 为 URL 模式 命名 。URL 模式 的 名 称 可 以 包含 任何 字符 串 ， 而 不 限定 
于 必须 是 有 效 的 Python 标识 符 。 为 URL 模式 命名 时 ， 要 确保 不 与 其 他 应 用 中 的 名 称 冲 突 。 如 果 你 把 URL 模 
式 命 名 为 comment ， 而 另 一 个 应 用 也 这 么 做 ， 在 模板 中 使 用 这 个 名 称 时 就 无 法 确定 该 生成 哪个 URL。 为 了 减 



























































少 冲 突 ， 可 以 为 URL 模式 的 名 称 加 上 前 缀 ， 比 如 说 使 用 应 用 程序 的 名 称 。 我 们 建议 使 


不 是 comment。 























jj myapp-comment， 而 
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7.8 URL 命名 空间 























URL 命名 空间 在 反 转 具名 URL 模式 时 具有 唯一 确定 性 ， 即 便 不 同 的 应 用 使 用 相同 的 名 称 也 不 怕 。 鉴 于 此 ， 
第 三 方 应 用 最 好 始终 把 URL 放 在 命名 空间 中 。 类 似 地 ，URL 命名 空间 在 部 署 多 个 应 用 程序 实例 时 也 能 正 到 
反 转 URL。 也 就 是 说 ， 同 一 个 应 用 程序 的 多 个 实例 使 用 相同 的 URL 模式 名 称 ， 而 通过 命名 空间 可 以 把 它们 
区 分 开 。 






























































正确 使 用 URL 命名 空间 的 Django 应 用 程序 可 以 在 同一 个 网 站 中 多 次 部 署 。 例 如 ，django.contrib.admin 中 
有 个 Adminsite 类 ， 可 以 轻易 部 署 多 个 管理 后 台 。URL 命名 空间 分 为 两 部 分 ， 而 且 都 是 字符 串 : 




































































1， 应 用 命名 空间 。 指 明 应 用 的 名 称 。 一 个 应 用 的 每 个 实例 都 具有 相同 的 应 用 命名 空间 。 例 如 ， 你 可 能 猜 
到 了 ，Django 管理 后 台 的 应 用 命名 空间 是 admin。 
2， 实 例 命名 空间 。 标 识 具 体 的 应 用 程序 实例 。 实 例 命 名 空间 在 整个 项 目 范围 内 应 该 是 唯一 的 。 不 过 ， 实 


网 命名 空间 可 以 与 应 用 命名 空间 相同 ， 供 应 用 的 默认 实例 使 用 。 例 如 ，Diango 管理 后 台 实 例 的 默认 实 
网 命 名 空间 是 adntn。 








































































































命名 空间 中 的 URL 使 用 : 运算 符 指定 。 例 如 ， 管 理 后 台 的 主页 使 用 admin:index 引用 。 其 中 ，admin 是 命名 
空间 ，index 是 URL 的 名 称 。 











命名 空间 还 可 以 艇 套 。 members:reviews:index 在 命名 空间 members 中 查找 命名 空间 reviews， 再 在 里 面 查找 
index URL, 























7.8.1 反 转 命名 空间 中 的 URL 








解析 命名 空间 中 的 URL 时 (如 reviews:index) ，Dijango 先 分 解 完全 限定 的 名 称 ， 然 后 尝试 做 下 述 查 找 : 
































1.， 首先 ，Django 查找 有 没有 匹配 的 应 用 命名 空间 (这 里 的 reviews) 。 为 此 ， 会 产 出 那个 应 用 的 实例 列 
表 。 


2. 如 果 有 这 么 一 个 应 用 实例 ，Django 返回 它 的 URL 解析 程序 。 当 前 应 用 可 以 通过 请 求 的 一 个 属性 指 
定 。 预 期 有 多 个 部 署 实例 的 应 用 应 该 在 处 理 的 请 求 上 设 定 current_app 属性 。 
3. 当前 应 用 也 可 以 手动 指定 ， 方 法 是 作为 参数 传 给 reverse() 函数 。 


4. 如 果 没 有 当前 应 用 ，Django 查找 默认 的 应 用 实例 。 默 认 应 用 实例 是 指 实例 命名 空间 与 应 用 命名 空间 匹 
配 的 实例 (在 这 里 是 指名 为 reviews 的 reviews 实例 ) 。 


5. 如 果 没 有 默认 的 应 用 实例 ，Django 选中 最 后 部 署 的 应 用 实例 ， 而 不 管 实例 的 名 称 。 
6. 如 果 第 1 步 找 不 到 匹配 的 应 用 命名 空间 ，Django 直接 把 它 视 作 实例 命名 空间 查找 。 































































































































































































对 向 套 的 命名 空间 来 说 ， 上 述 步 又 不 断 重复 ， 直 到 视图 名 称 为 止 。 视 图 名 称 在 找到 的 命名 空间 中 解析 成 
URL., 


7.8.2 URL 命名 空间 和 引入 的 URL 配置 








把 引入 的 URL 配置 放 入 命名 空间 中 有 两 种 方式 。 第 一 种 ， 在 URL 模式 中 为 inctude() 提供 应 用 和 实例 命名 
空间 。 例 如 : 


url(r'^reviews/', include('reviews.urls', 
namespace='author-reviews', 
app_name=' reviews')), 











上 述 代码 把 reviews.urls 中 定义 的 URL 放 在 应 用 命名 空间 reviews 中 ， 放 在 实例 命名 空间 author-reviews 
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UD 


中 。 第 二 种 方式 是 ， 引 入 包含 命名 空间 数据 的 对 象 。 如 果 使 用 include() 引入 一 组 urt() 实例 ， 那 个 对 象 
的 URL 都 添加 到 全 局 命名 空间 中 。 然 而 ，inctude() 的 参数 还 可 以 是 一 个 三 元 素 元 组 ， 其 内 容 如 下 : 

















(<list of url() instances>, <application namespace>, <instance namespace>) 
例如 : 


from django.conf.urls import include, url 
from . import views 


reviews_patterns = [ 


url(r'^$', views.IndexView.as_view(), name='index'), 
url(r'^(?P<pk>\d+)/$', views.DetailView.as_view(), name='detail'), 


url(r'^reviews/', include((reviews patterns, 'reviews', 'author-reviews'))), 





上 述 代码 把 指定 的 URL 模式 引入 指定 的 应 用 和 实例 命名 空间 中 。 例 如 ， 部 署 的 Django 管理 后 台 是 Adminsite 
的 实例 。Adminsite 对 象 有 个 urls 属性 ， 它 的 值 是 一 个 三 元 素 元 组 ， 包 含 相应 管理 后 台 的 所 有 URL 模式 ， 以 
及 应 用 命名 空间 'admin' 和 管理 后 台 实 例 的 名 称 。 部 署 管 理 后 台 实 例 时 ， 引 入 项 目的 urlpatterns 中 的 就 是 


这 个 urls 属性 。 















































记得 要 把 一 个 元 组 传 给 include()。 如 果 直 接 传人 三 个 参数 ， 例 如 incLude(reviews_patterns，'reviews ' ， 
'author-reviews' )，Django 不 会 抛 出 错误 ， 但 是 根据 include() 的 签名 ，'reviews' 是 实例 命名 空间 ，'au- 
thor-reviews' 是 应 用 命名 空间 ， 而 正确 的 顺序 应 该 反 过 来 。 











7.9 接 下 来 


本 章 介绍 了 很 多 高 级 的 视图 和 URL 配置 技巧 。 接 下 来 ， 在 第 8 音 ， 我 们 将 讨论 Django 模板 系统 的 高 级 话 


日 
题 。 
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虽然 你 基本 上 是 作为 编写 者 去 使 用 Django 的 模板 语言 ， 但 是 有 时 可 能 想 定制 或 扩展 模板 引擎 ， 例 如 实现 没有 
自 带 的 功能 ， 或 者 以 某 种 方式 简化 工作 。 


本 章 深入 讨论 Django 的 模板 系统 ， 让 你 知道 如 何 扩展 这 一 系统 ， 也 满足 你 对 内 部 运作 机 制 的 好 奇 心 。 此 外 ， 
本 章 还 涵盖 自动 转 义 特性 。 这 是 一 项 安全 措施 ， 在 使 用 Django 的 过 程 中 你 肯定 会 注意 到 它 的 存在 。 
























































8.1 模板 语言 回顾 








首先 ， 我 们 快速 回顾 一 下 第 3 半 介 绍 的 几 个 术语 : 











。 模板 是 文本 文档 或 普通 的 Python 字符 串 ， 使 用 Django 模板 语言 标记 。 模 板 中 有 模板 标签 和 变量 。 
。 模板 标签 是 模板 中 的 一 种 符号 ， 用 于 做 特定 的 事情 。 这 样 定义 相当 星 涩 。 我 们 来 举 些 例子 ， 模板 标签 
可 以 生成 内 容 、 用 做 控制 结构 if 语句 或 for 循环 ) 、 从 数据 库 中 获取 内 容 ， 或 者 访问 其 他 模板 标 

签 。 模 板 标签 放 在 {% 和 只 之 间 : 
































{% if itLs_ Logged_in %} 
Thanks for logging in! 
{% else %} 
Please Log in. 
{% endif %} 














。 变量 也 是 模板 中 的 一 种 符号 ， 用 于 输出 值 。 变 量 放 在 {{ 和 站 之 间 : 














My first name is {{ first_name }}. My Last name is {{ Last_name }}. 














=， 





。 上 下 文 是 传 给 模板 的 名 值 映 射 〈 类 似 于 Python 字典 ) 。 
模板 泻 染 上 下 文 的 过 程 是 把 变量 所 在 的 位 置 蔡 换 成 上 下 文中 的 值 ， 并 执行 所 有 模板 标签 。 






































关于 这 些 术语 的 更 多 说 明 ， 参 阅 第 3 音 。 本 章 余下 的 内 容 讨论 扩展 模板 引擎 的 方式 。 不 过 ， 在 此 之 前 我 们 要 
简单 说 明 一 下 第 3 章 没 有 涵盖 的 内 部 细节。 




















8.2 RequestContext 和 上 下 文 处 理 器 


模板 要 在 上 下 文中 泻 染 。 上 下 文 是 django.template.Context 的 实例 ， 不 过 Django 还 提供 了 一 个 子 类 ，djan- 
go.tempLate.RequestContext， 其 行为 稍 有 不 同 。 



































RequestContext 默认 为 模板 上 下 文 添 加 很 多 变量 ， 例 如 HttpRequest 对 象 或 当前 登录 用 户 的 信息 。 

















使 用 render() 快捷 方式 时 ， 如 果 没 有 明确 传人 其 他 上 下 文 ， 默 认 使 用 RequestContext。 来 看 下 面 两 个 视图 : 




















from django.template import loader, Context 


def view 1(request): 
WR 
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t = Loader .get_tempLate( 'tempLate1.htmL ' ) 
c = Context({ 
‘app': "My app', 
'User': request.user, 
'ip_address': request.META['REMOTE_ADDR'], 
'message': 'I am view 1.' 
}) 


return t.render(c) 


def view 2(request): 

We 

t = loader.get_ template('template2.html') 

c = Context({ 
'app': 'My app', 
'User': request.user, 
'ip_address': request.META['REMOTE_ADDR'], 
'message': 'I am the second view.' 

}) 


return t.render(c) 


(注意 ， 这 里 我 故意 没有 使 用 render() 的 快捷 方式 ， 而 是 自己 动手 加 载 模板 、 构 建 上 下 文 对 象 ， 再 泻 染 模 











板 。 我 把 这 些 步 又 写 出 来 ， 是 为 了 便于 讨论 。) 











在 这 两 个 视图 中 ， 我 们 向 模板 传人 了 相同 的 三 个 变量 : app、user 和 ip_address。 如 果 能 去 掉 这 些 奸 


复 不 是 














更 好 吗 ? RequestContext 和 上 下 文 处 理 器 就 是 为 解决 这 种 问题 而 出 现 的 。 上 下 文 处 理 器 用 于 指定 自动 在 各 个 

















上 下 文中 设 定 的 变量 ， 这 样 就 无 需 每 次 调用 render() 时 都 指定 。 








为 此 ， 演 染 模 板 时 要 把 Context 换 成 RequestContext。 使 用 上 下 文 处 理 器 最 低层 的 做 法 是 创建 一 些 处 理 器 ， 





将 其 传 给 RequestContext。 使 用 上 下 文 处 理 器 改写 上 述 示例 得 到 的 代码 如 下 : 








from django.template import loader, RequestContext 


def custom proc(request): 
# 一 个 上 下 文 处 理 器 ,提供 'app'、'user' 和 'ip_address' 
return { 


app': 'My app', 
'User': request.user, 
'ip_address': request.META['REMOTE_ADDR'] 


def view 1(request): 


其 
t = Loader .get_tempLate( 'tempLate1.htmL ' ) 
Cc = RequestContext(request， 


{'message': 'I am view 1.'}, 
processors=[custom_proc]) 
return t.render(c) 


def view 2(request): 


i 
t = loader.get template('template2.html') 
Cc = RequestContext(request， 


{'message': 'I am the second view.'}, 
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processors=[custom_proc]) 
return t.render(c) 


下 面 分 析 一 下 这 段 代码 : 





。 首先 ， 定 义 函 数 custom_proc。 这 是 一 个 上 下 文 处 理 器 ， 它 的 参数 是 一 个 HttpRequest 对 象 ， 返 回 值 是 











一 个 字典 ， 包 含 要 在 模板 上 下 文中 使 用 的 变量 。 就 这 么 简单 。 














。 我 们 修改 了 那 两 个 视图 函数 ， 把 Context 换 成 RequestContext。 构 建 这 种 上 下 文 的 方式 有 两 处 不 同 : 

















其 一 ，RequestContext 要 求 第 一 个 参数 必须 是 一 个 HttpRequest 对 象 ， 即 传 给 视图 函数 的 那个 参数 


(request) ; 其 二 ，RequestContext 接受 可 选 的 processors 参数 ， 其 值 是 要 使 用 的 上 下 文 处 理 器 列表 





或 元 组 。 这 里 ， 我 们 传人 的 是 前 面 定 义 的 那个 处 理 器 custom_proc。 














。 现在 ， 各 个 视图 在 构建 上 下 文 时 无 需 包含 app、user 或 ip_address， 因 为 custom_proc 已 经 提供 。 
。 如 果 需 要 ， 视 图 仍 可 以 提供 其 他 模板 变量 。 这 里 ， 我 们 为 两 个 视图 设 定 了 不 同 的 message 模板 变量 。 



































我 在 第 3 章 介 绍 了 render() 快捷 方式 ， 这 样 能 避免 在 模板 中 自己 动手 调用 Loader .get_tempLate()、 创 建 上 下 














文 ， 再 调用 render() 方法 。 














为 了 说 明 上 下 文 处 理 器 的 低层 工作 方式 ， 上 述 示例 没有 使 用 render() 快捷 方式 。 但 是 ， 使 用 上 下 文 处 理 器 时 











可 以 这 么 做 ， 也 推荐 这 么 做 。 为 此 ， 要 使 用 context_instance 人 参数， 如 下 所 示 : 








from django.shortcuts import render 
from django.template import RequestContext 


def custom proc(request): 
# 一 个 上 下 文 处 理 器 ， 提 供 'app'、'user' 和 'ip_address' 
return { 


app': 'My app '， 

"User': request.user, 

'ip_address': request.META[ 'REMOTE_ADDR '] 
} 


def view 1(request): 
# ... 
return render(request, 'templatel.html', 
{'message': 'I am view 1.'}, 
context_instance=RequestContext( 
request, processors=[custom_ proc] 


) 


def view 2(request): 
和 
return render(request, 'template2.html', 
{'message': 'I am the second view.'}, 
context_instance=RequestContext( 
request, processors=[custom proc] 


) 


在 这 两 个 视图 中 ， 我 们 把 演 染 模板 的 代码 缩减 到 只 有 一 行 (有 换行 ) 。 这 是 进步 ， 
性 ， 这 么 做 无 异 于 走向 另 一 个 极端 。 我 们 去 掉 了 数据 (模板 变量 ) na 但 是 
processors 的 代码 ) 中 的 重复 。 

















但 是 考虑 到 代码 的 简洁 
增加 了 代码 (调用 
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如 果 每 一 次 都 要 输入 processors， 使 用 上 下 文 处 理 需 省 不 了 多 少 事 。 鉴 于 此 ，Django 提供 了 全 局 上 下 文 处 理 
器 。context_processors 设置 (在 settings.py 文件 中 ) 指明 始终 提供 给 RequestContext 的 上 下 文 处 理 器 。 
这 样 便 不 用 每 次 使 用 RequestContext 时 都 指定 processors 参数 了 。 












































context_processors 的 默认 值 如 下 : 


"Context_processors': [ 
'django.template.context_processors.debug', 
'django.template.context_processors.request', 
"django.contrib.auth.context_processors.auth ' ， 
"django.contrib.messages.Ccontext_processors.messages ' ， 


]， 


这 是 一 个 可 调用 对 象 列表 ， 接 口 与 前 文 定 义 的 custom_proc 函数 一 样 一 一 参数 是 一 个 请 求 对 象 ， 返 回 值 是 一 
个 字典 ， 包 含 要 合并 到 上 下 文中 的 变量 。 注 意 ，context_processors 中 的 值 是 字符 串 ， 因 此 人 处理 器 要 在 
Python 路 径 中 (这 样 才能 在 设置 中 引用 ) 。 


指定 的 各 个 处 理 器 按 顺序 运用 。 因 此 ， 如 果 一 个 处 理 器 向 上 下 文中 添加 了 一 个 变量 ， 而 后 面 一 个 处 理 器 又 添 
加 了 一 个 同名 变量 ， 那 么 后 一 个 将 覆盖 前 一 个 。Django 提供 了 几 个 简单 的 上 下 文 处 理 器 ， 包 含 默 认 启 用 的 那 
几 个 。 下 面 几 小 节 详 述 。 






































































































































8.2.1 auth 


django.contrib.auth.context_processors.auth 





启用 这 个 处 理 器 后 ，RequestContext 中 将 包含 下 述 变量 : 
































。 user: auth.User 的 实例 ， 表 示 当 前 登录 的 用 户 (如 未 登录 ， 是 AnonymousUser 实例 ) 。 
。 perms: django.contrib.auth.context_processors.PermWrapper 实例 ， 表 示 当 前 登录 用 户 拥 有 的 权限 。 








8.2.2 debug 


django.tempLate.context_processors.debug 
































启用 这 个 处 理 髓 后 ，RequestContext 中 将 包含 下 面 两 个 变量 ， 但 前 提 是 DEBUG 设置 的 值 是 True， 而 且 INTER- 
NAL_IPS 设置 中 包含 请 求 的 卫 地 址 (request.META[ 'REMOTE_ADDR']) : 























。 debug: True。 可 以 在 模板 中 测试 是 否 在 DEBUG 模式 中 。 


。 sqL_queries: {'sql': ..，'time': .字典 构成 的 列表 ， 表 示 处 理 请 求 的 过 程 中 执行 的 SQL 查询 及 其 
用 时 。 列 表 中 的 值 按 查 询 的 执行 顺序 排列 ， 在 访问 时 惰性 生成 。 


























8.2.3 ii8n 
django.template.context_processors.ii8n 


启用 这 个 处 理 器 后 ，RequestContext 中 将 包含 下 面 两 个 变量 








。 LANGUAGES:， LANGUAGES 设置 的 值 。 





。 LANGUAGE_CODE: 如 果 request.LANGUAGE_CODE 存在 ， 返 回 它 的 值 ， 否则 返回 LANGUAGE_CODE 设置 的 值 。 
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8.2.4 media 


django.tempLate.context_processors.media 











启用 这 个 处 理 器 后 ，RequestContext 中 将 包含 MEDIA_URL 变量 ， 提 供 MEDIA_URL 设置 的 值 。 


8.2.5 static 


django.tempLate.context_processors.static 














启用 这 个 处 理 程 序 后 ，RequestContext 中 将 包含 STATIC_URL 变量 ， 提 供 STATIC_URL 设置 的 值 。 




















8.2.6 csrf 


django.template.context_processors.csrf 





























这 个 处 理 器 添加 一 个 令 牌 ， 供 csrf_token 模板 标签 使 用 ， 用 于 防范 跨 站 请 求 伪造 (参见 第 19 章 ) 。 


8.2.7 request 


django.template.context_processors.request 








启用 这 个 处 理 器 后 ，RequestContext 中 将 包含 request 变量 ， 它 的 值 是 当前 的 HttpRequest 对 象 。 








8.2.8 messages 


django.contrib.messages.context_processors.messages 


启用 这 个 处 理 器 后 ，RequestContext 中 将 包含 下 面 两 个 变量 : 





























。 messages: 消息 框架 设 定 的 消息 列表 (里 面 的 值 是 字符 中 


。 DEFAULT_MESSAGE_LEVELS: 消息 等 级 名 称 到 数字 值 的 映射 。 


Ud 
— 
o 





8.3 自 定义 上 下 文 处 理 器 的 指导 方针 





上 下 文 处 理 器 的 接口 十 分 简单 ， 它 就 是 普通 的 Python 函数 ， 有 一 个 参数 ， 是 一 个 HttpRequest 对 象 ， 返 回 一 
个 字典 ， 用 于 添加 到 模板 上 下 文中 。 上 下 文 处 理 器 必须 返回 一 个 字典 。 下 面 是 自 定义 处 理 器 的 几 个 小 贴 士 : 










































































。 上 下 文 处 理 器 应 该 尽量 负责 较 少 的 功能 。 处 理 器 易于 合用 ， 因 此 应 该 把 功能 分 成 逻辑 片段 ， 供 以 后 复 
用 。 


。 记 住 ，TEMPLATE_CONTEXT_PROCESSORS 中 列 出 的 各 个 上 下 文 处 理 器 在 那个 设置 文件 管辖 的 每 个 模板 中 都 
可 用 ， 因 此 应 该 为 变量 挑选 不 易 与 模板 自身 设 定 的 变量 冲突 的 名 称 。 因 为 变量 区 分 大 小 写 ， 所 以 让 处 

理 器 提供 的 变量 都 使 用 大 写 不 失 为 一 个 好 主意 。 

。 自 定 义 的 上 下 文 处 理 器 可 以 放 在 代码 基 的 任何 位 置 。Django 只 关心 TEMPLATES 设置 中 的 “con- 
text_processors' 选项 或 者 Engine 的 context_processors 参数 (直接 使 用 Engine 时 ) 有 没有 指向 你 
的 上 下 文 处 理 器 。 尽 管 如 此 ， 约 定 的 做 法 是 把 上 下 文 处理 器 保存 在 应 用 或 项 目 中 一 个 名 为 con- 
text_processors.py 的 文件 中 。 
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8.4 自动 转 义 HTML 


使 用 模 
说 : 


板 生 成 HTML 时 ， 变 量 的 值 可 能 包含 特殊 的 字符 ， 对 得 到 的 HTML 产生 影响 。 对 下 述 模板 片段 来 





Hello, {{ name }}. 


-3 


PE 一 看 





， 这 样 显示 用 户 的 名 字 没 什么 危害 。 但 是 ， 








<script>alert('hello' )</script> 


此 时 » 


演 染 模板 后 得 到 的 结果 是 : 


Hello, <script>alert('hello')</script> 


因此 ， 





如 果 用 户 输入 的 名 字 是 这 样 的 呢 : 














浏览 器 会 弹出 一 个 对 话 框 。 同 样 ， 如 果 名 字 中 包含 '<' 符号 呢 : 


<b>username 


此 时 » 


演 染 模板 后 得 到 的 结果 是 : 


Hello, <b>username 


这 样 ， 


SI 
局 用 











户 可 以 利用 这 种 漏洞 做 些 坏事 。 





网 页 中 的 后 续 内 容 都 会 显示 为 粗 体 。 显 然 ， 


用 户 提 交 的 数据 不 该 盲目 信任 ， 不 能 直接 插入 网 页 ， 因 为 








这 种 安全 漏洞 称 为 跨 站 脚本 攻击 (Cross Site Scripting，XSS) 。 (安全 方面 的 话题 参见 第 19 草 。) 为 了 避免 
这 种 漏洞 ， 有 两 个 选择 : 


1 


2. 





每 个 不 信任 的 变量 都 传 给 escape 过 滤器 ， 把 有 潜在 危害 的 HTML 字符 转换 成 无 危害 的 。Django 起 初 
的 几 年 默认 采用 这 种 方案 ， 它 的 问题 是 把 责任 强加 到 开发 者 或 模板 编写 者 身上 了 ， 你 要 确保 转 义 


























切 。 但 是 ， 忘 记 转 义 数 据 是 常事 。 












































利用 Django 的 自动 转 义 HTML 特性 。 本 节余 下 的 内 容 说 明 自 动 转 义 的 工作 方式 。 




















Django 默认 转 义 模板 中 的 每 个 变量 标签 。 具 体 而 言 ， 转 义 的 是 下 面 五 个 字符 : 


< 转换 成 &Lt; 

> 转换 成 &gt; 

，( 单 引号 ) 转换 成 &#39; 
"”( 双 引号 ) 转换 成 &quot; 
& 转换 成 &amp; 

















我 们 要 再 次 强调 ， 这 个 行为 默认 已 启用 。 如 果 使 











8.4.1 如 何 禁 用 





自动 转 义 可 以 在 整 站 禁用 、 在 模板 层林 


























] Django 的 模板 系统 ， 就 能 受到 这 一 措施 的 保护 。 

















的 数据 泻 染 成 原始 HTML， 无 需 转 义 。 


例如 ， 








可 能 在 数据 库 中 存储 了 授信 的 HTML blobp， 想 直接 将 其 插入 模板 。 或 者 ， 使 用 Django 的 模板 系统 生 
成 非 HTML 文本 ,例如 电子 邮件 。 























或 在 变量 层 禁 用 。 为 什么 要 禁用 呢 ? 因为 有 时 候 想 把 模板 变量 包含 
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在 单个 变量 中 禁用 
































若 想 在 单个 变量 中 禁用 自动 转 义 ， 使 用 safe 过 滤器 : 

















This will be escaped: {{ data }} 
This will not be escaped: {{ datalsafe }} 





这 个 过 滤器 的 作用 可 以 理解 为 “无 需 转 义 ， 可 以 放心 使 用 *"， 或 者 “可 以 安全 解释 为 HTML”*。 这 里 ， 如 果 data 
中 包含 '<b>'， 得 到 的 结果 为 : 





This will be escaped: &lt;b&at; 
This will not be escaped: <b> 


在 模板 中 的 块 里 禁用 








若 想 在 模板 中 控制 自动 转 义 行为 ， 把 模板 (或 其 中 一 部 分 ) 放 在 autoescape 标签 里 ， 如 下 所 示 : 





{% autoescape off %} 
Hello {{ name }} 
{% endautoescape %} 





autoescape 标签 的 参数 为 on 或 off。 有 时 需要 强制 自动 转 义 ， 有 时 则 想 禁 用 。 下 面 举 个 例子 : 





Auto-escaping is on by default. Hello {{ name }} 


{% autoescape off %} 
This will not be auto-escaped: {{ data }}. 


Nor this: {{ other_data }} 
{% autoescape on %} 
Auto-escaping applies again: {{ name }} 
{% endautoescape %} 
{% endautoescape %} 


autoescape 标签 的 作用 能 延伸 到 扩展 当前 模板 的 模板 ， 以 及 通过 include 标签 引入 的 模板 一 一 这 一 点 与 其 他 
块 标签 一 样 。 例 如 : 


# base.html 


{% autoescape off %} 
<h1>{% block title %}{% endblock %}</hi> 
{% block content %} 
{% endblock %} 

{% endautoescape %} 


# child.html 
{% extends "base.html" %} 


{% block title %}This & that{% endblock %} 
{% block content %}{{ greeting }}{% endblock %} 











基 模 板 禁 用 了 自动 转 义 ， 因 此 子 模 板 也 将 禁用 。greeting 变量 包含 字符 串 <b>Hello!</b> 时 ， 演 染 得 到 的 
HTML 如 下 : 











<h1>This & that</h1> 
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<b>Hello!</b> 








一 般 来 说 ,模板 编写 人 无 需 过 多 关注 自动 转 义 。Python 侧 的 开发 者 (编写 视 
哪些 情况 下 不 用 转 义 数据 ， 并 且 为 数据 做 好 相应 的 标记 ， 这 样 泻 染 模板 得 到 的 结果 才 符 合 预 期 。 






























































图 和 自 定义 过 滤器 的 人 ) 要 考虑 




















如 果 使 用 模板 的 环境 不 确定 是 否 启用 了 自动 转 义 ， 应 该 添加 escape 过 滤器 ， 用 于 转 义 需要 转 义 的 变量 。 如 果 














启用 了 自动 转 义 ，escape 过 滤器 会 再 次 转 义 数据 ， 但 是 这 样 做 并 无 坏处 ， 因 为 escape 过 滤器 对 自动 转 义 过 的 





变量 没有 影响 。 


8.4.2 自动 转 义 过 滤器 参数 中 的 字符 串 字 面 量 


前 面 说 过 ， 过 滤器 的 参数 可 以 是 字符 串 ， 侈 如 : 





{{ dataldefault:"This is a string literal." }} 


字符 串 字 面 量 插入 模板 时 不 会 自动 转 义 ， 就 像 是 经 过 safe 过 滤 右 人 处理 过 了 一 内 



































写 人 员 负 责 控制 字符 串 字 面 量 中 的 内 容 ， 他 们 在 编写 模板 时 可 以 确保 正确 转 义 了 文本 。 











因此 ， 你 应 该 编写 : 
{{ dataldefault:"3 &Lt; 2" }} 
而 不 是 : 
{{ dataldefault:"3 < 2" }} 人 {# <-- 不 对 ! 别 这 么 做 。 扒 


从 变量 中 得 出 的 数据 不 是 如 此 。 变 量 的 内 容 在 需要 时 会 自动 转 义 














8.5 模板 加 载 内 部 机 制 





通常 ， 我 们 把 模板 保存 在 文件 系统 中 的 文件 里 ， 而 不 直接 使 用 低 


























， 因 为 它们 不 在 模板 编 











层 的 Template API。 建 





#。 这 样 处 理 的 原因 是 ， 模 板 乡 






































写 人 的 控制 范围 内 。 





议 把 模板 保存 在 一 个 














专门 的 目录 中 。Django 在 多 个 位 置 搜索 模板 目录 ， 具 体 是 哪些 取决 于 模板 加 载 设置 (参见 8.5.2 节 ) ,但 是 


指定 模板 目录 最 基本 的 方式 是 使 用 DIRS 选项 。 


8.5.1 DIRS 选项 














告诉 Django 模板 目录 有 哪些 的 方法 是 使 用 设置 文件 中 TEMPLATES 设置 的 DIRS 选项 ， 或 者 是 Engine 的 dirs 参 
数 。 这 个 选项 的 值 是 一 个 字符 串 列 表 ， 包 含 指 向 模板 目录 的 完整 路 径 : 




















TEMPLATES = [ 





{ 
'BACKEND': 'django.tempLate.backends.django.DjangoTempLates ' ， 
“DIRS [ 
'/home/html/templates/\lawrence.com', 
'/home/html/templates/default', 
]， 
}, 


] 











模板 可 以 放 在 任何 位 置 ， 只 要 Web 服务 器 有 权限 读 取 目 录 及 里 二 

















ji 的 模板 即 可 。 模 板 的 和 











六 展 名 不 限 ， 可 以 是 








.html 或 .txt， 甚 至 可 以 没有 。 注 意 ， 这 里 的 路 径 应 该 使 用 Unix 风格 的 正 斜 线 ， 即 便 在 Windows 中 也 是 如 


此 。 
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8.5.2 加 载 器 的 类 型 


Django 默认 使 用 基于 文件 系统 的 模板 加 载 器 (loader) ， 不 过 除 此 之 外 Django 还 自 带 了 几 个 其 他 的 加 载 器 ， 
它们 知道 如 何 从 其 他 源 加 载 模板 。 其 中 ， 最 常 使 用 的 是 应 用 目录 加 载 器 ， 参 见 下 面 的 说 明 。 


















































文件 系统 加 载 器 
filesystem.Loader 


根据 DIRS 的 值 ， 从 文件 系统 中 加 载 模板 。 这 是 默认 启用 的 加 载 器 。 然 而 ， 如 果 不 设 定 DIRS 选项 ， 这 个 加 载 
器 找 不 到 任何 模板 。 


TEMPLATES = [{ 
"BACKEND ' : "django.tempLate.backends.django.DjangoTempLates ' ， 
'DIRS': [os.path.join(BASE_DIR, 'tempLates ' )] ， 

}] 


应 用 目录 加 载 器 


app_directories.Loader 

















从 文件 系统 中 的 Django 应 用 里 加 载 模板 。 这 个 加 载 器 在 INSTALLED_APPS 列 出 的 各 个 应 用 中 查找 templates 子 
目录 。 如 果 找 到 ，Django 在 其 中 查找 模板 。 这 意味 着 ， 应 用 可 以 自 带 模板 。 通 过 这 一 行为 ， 便 于 分 发 带 默 认 
模板 的 Django 应 用 。 例 如 ， 对 下 面 的 设置 来 说 : 
































INSTALLED_APPS = ['myproject.reviews', 'myproject.music'] 


get_tempLate( 'foo.html') 会 按 顺 序 在 下 述 目 录 中 查找 foo.html: 





。 /path/to/myproject/reviews/templates/ 


。 /path/to/myproject/music/templates/ 








而 且 使 用 最 先 找到 的 那个 。 





鉴于 此 ，INSTALLED_APPS 中 罗列 应 用 的 顺序 是 十 分 重要 的 ! 








假如 你 想 自 定义 Django 的 管理 后 台 ， 你 可 以 选择 覆盖 django.contrib.admin 中 的 admin/base_site.html 模 
板 ， 把 自 定 义 的 模板 admin/base_site.html 保存 在 myproject.reviews 应 用 中 。 



































此 时 ， 在 INSTALLED_APPS 中 必须 把 myproject.reviews 放 在 django.contrib.admin 前 面 ， 否 则 将 先 加 载 djan- 
go.contrib.admin， 你 自 定义 的 模板 就 被 忽略 了 。 


























注意 ， 加 载 器 首次 运行 时 会 执行 一 项 优化 措施 : 缓存 INSTALLED_APPS 中 有 templates 子 目 录 的 包 。 














内需 把 APP_DIRS 选项 设 为 True 即 可 启用 这 个 加 载 器 ， 











TEMPLATES = [{ 
'BACKEND': 'django.tempLate.backends.django.DjangoTempLates ' ， 
'APP_DIRS': True， 

}] 


其 他 加 载 器 
此 外 还 有 几 个 模板 加 载 器 : 
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。 django.tempLate.Loaders.eggs.Loader 
。 django.template. loaders.cached.Loader 


。 django.template. loaders.locmem.Loader 


这 些 加 载 器 默认 禁用 ， 不 过 可 以 在 TEMPLATES 设置 中 为 DjangoTemplates 后 端 添加 'Loaders' 选项 ， 或 者 把 
Loaders 参数 传 给 Engine 启用 。 这 些 高 级 加 载 器 的 详细 说 明 ， 以 及 构建 自 定 义 加 载 器 的 方法 参见 Django 项 目 
的 网 站 。 




















8.6 扩展 模板 系统 


现在 ， 我 们 了 解 了 一 些 模板 系统 的 内 部 细节 ， 下 面 来 看 如 何 扩展 这 个 系统 。 对 模板 系统 的 定制 ， 基 本 上 是 自 
定义 模板 标签 和 (或 ) 过 滤器 。 虽 然 Django 模板 语言 自 带 了 很 多 内 建 的 标签 和 过 滤器 ， 但 是 有 时 也 需要 自己 
创建 一 些 标签 和 过 滤器 ， 满 足 自 己 的 需求 。 幸 好 ， 这 并 不 难 。 














8.6.1 代码 布局 


自 定 义 的 模板 标签 和 过 滤器 必须 放 在 一 个 Django 应 用 中 。 如 果 与 现 有 应 用 有 关 ， 可 以 放 在 现 有 应 用 中 ， 否 
则 ， 应 该 专门 创建 一 个 应 用 存放 。 应 用 中 应 该 有 个 templatetags 目录 ， 与 models.py、views.py 等 文件 放 在 
同一 级 。 如 果 没 有 这 个 目录 ， 创 建 一 个 ， 别 忘 了 __init__.py 文件 ， 这 样 才能 保证 所 在 目录 是 一 个 Python 
包 。 





















































添加 这 个 模块 之 后 ， 要 重启 服务 器 方 能 在 模板 中 使 用 自 定义 的 标签 或 过 滤器 。 自 定义 的 标签 和 过 滤器 在 tem- 
platetags 目录 里 的 一 个 模块 中 。 


模块 文件 的 名 称 是 加 载 标签 所 用 的 名 称 ， 所 以 要 小 心 选择 ， 别 与 其 他 应 用 中 的 自 定义 标签 和 过 滤器 冲突 了 。 
假如 自 定义 的 标签 (过 滤器 ) 放 在 review_extras.py 文件 中 ， 应 用 的 布局 可 能 是 下 面 这 样 : 



































reviews/ 
__init .py 
models.py 
templatetags/ 
__init .py 
review extras.py 
Views.py 


在 模板 中 则 这 样 使 用 : 


{% load review extras %} 











包含 自 定义 标签 的 应 用 必须 在 INSTALLED_APPS 中 列 出 ， 这 样 {% load %} 标签 才能 起 作用 。 




















背后 的 运作 方式 


举 再 多 的 例子 也 不 如 阅读 源码 ， 学 习 Django 是 如 何 定 义 默 认 的 过 滤器 和 标签 的 。 过 滤器 和 标 
签 分 别 在 django/template/defaultfilters.py 和 django/template/defaulttags.py 文件 中 。 
load 标签 的 更 多 信息 参阅 文档 。 
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8.6.2 创建 模板 库 
不 管 是 自 定 义 标 签 还 是 过 滤器 ， 第 一 件 事 都 是 创建 模板 库 一 一 这 是 让 Django 勾 住 的 基本 要 求 。 
创建 模板 库 分 为 两 步 : 






































。 首先 ， 决 定 把 模板 库 放 在 哪个 Django 应 用 中 。 如 果 应 用 是 使 用 manage.py startapp 创建 的 ， 可 以 把 模 

板 库 放 在 那里 ， 如 若 不 然 ， 可 以 专门 创建 一 个 应 用 ， 用 于 存放 模板 库 。 我 们 推荐 后 者 ， 因 为 自 定义 的 

标签 和 过 滤器 可 能 对 以 后 的 项 目 有 用 。 不 管 怎么 做 ， 一 定 要 把 应 用 添加 到 INSTALLED_APPS 设置 中 。 具 

体 怎 么 做 ， 稍 后 说 明 。 

。 其 次 ， 在 Django 应 用 中 合适 的 包 里 创建 templatetags 目录 。 这 个 目录 应 该 与 models.py、views.py 等 
文件 放 在 同一 级 。 例 如 : 



























































books/ 
__init .py 
models.py 
templatetags/ 
views.py 





在 templatetags 目录 中 创建 两 个 空 文件 __init__.py (告诉 Python 这 是 包含 Python 代码 的 包 ) 和 存放 自 定 
义 标签 (过 滤器 ) 的 文件 。 后 者 的 名 称 是 加 载 标签 所 用 的 名 称 。 例 如 ， 自 定义 的 标签 (过 滤器 ) 保存 在 re- 
view_extras.py 文件 中 ， 那 么 在 模板 中 要 这 么 加 载 : 






































{% load review extras %} 








{% load %} 标签 在 INSTALLED_APPS 设置 中 查找 包含 自 定义 标签 (过 滤器 ) 的 应 用 ， 而 且 只 从 应 用 中 加 载 模板 
库 。 这 是 一 个 安全 特性 ， 以 便 在 同一 台电 脑 中 存 贮 多 个 模板 库 的 Python 代码 ， 而 不 让 每 个 Django 实例 都 能 
访 问 oo 


丸 
templatetags 包 中 的 模块 数量 不 限 。 记 住 ，{% load 季 语句 加 载 的 是 指定 的 Python 模块 ， 而 不 是 应 用 。 
































果 模 板 库 不 与 任何 模型 或 视图 绑 定 ，Django 应 用 中 可 以 只 有 templatetags 包 。 事 实 上 ， 这 也 相当 常见 。 








EA 








创建 存放 标签 (过 滤器 ) 的 Python 模块 之 后 ， 剩 下 的 就 是 编写 Python 代码 了 。 代 码 怎 么 写 ， 取 决 于 定义 的 
是 过 滤器 还 是 标签 。 一 个 有 效 的 标签 库 必须 有 一 个 名 为 register 的 模块 层 变量 ， 其 值 是 template.Library 的 
实例 。 


标签 和 过 滤器 都 通过 这 种 方式 注册 。 因 此 ， 在 模块 顶部 要 插入 下 述 代码 : 






































from django import tempLate 


register = template.Library() 


8.7 自 定义 模板 标签 和 过 滤器 


















































Django 的 模板 语言 自 带 了 丰富 的 标签 和 过 滤器 ， 能 满足 常见 的 表现 逻辑 需求 。 但 是 ， 这 些 内 建 的 标签 和 过 滤 
器 可 能 缺少 你 需要 的 功能 。 








我 们 可 以 扩展 模板 引擎 ， 使 用 Python 自 定 义 标签 和 过 滤器 ， 然 后 使 用 {% Load 好 标签 加 载 ， 让 自 定义 的 标 
签 和 过 滤器 可 在 模板 中 使 用 。 
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8.7.1 自 定 义 模板 过 滤器 


自 定义 的 过 滤器 其 实 就 是 普通 的 Python 函数 ， 接 受 一 个 或 多 个 参数 ， 








1， 变 量 的 值 (输入 ) ， 不 一 定 是 字符 串 。 
2， 参 数 的 值 ， 可 以 有 默认 值 ， 也 可 以 留 空 。 




















例如 ， 对 {{ varlfoo:"bar”}} 来 说 ， 传 给 foo 过 滤器 的 变量 是 var， 人 参数 是 "bar"。 因 为 模板 语言 没有 提供 





异常 处 理 功能 ， 所 以 模板 过 滤器 抛 出 的 异常 会 以 服务 器 错误 体现 出 来 。 

















鉴于 此 ， 模 板 过 滤器 应 该 避免 抛 出 异常 ， 而 是 回落 到 其 他 合理 的 值 。 如 果 输 入 明显 有 问题 ， 














常 ， 以 免 深 埋 缺 陷 。 下 面 是 一 个 示例 过 渡 右 的 定义 : 











def cut(vaLue，arg) : 


"""Removes all values of arg from the given string 
return value.replace(arg, '') 


这 个 过 滤器 的 用 法 举例 如 下 : 





{{ somevariable|cut:"0" }} 





多 数 过 滤器 没有 参数 。 此 时 ， 在 函数 中 留 空 参数 即 可 。 例 如 : 


def Lower(vaLue): # 只 有 一 个 参数 
"""Converts a string into all Lowercase 


Wn 


return value.lower() 


注册 自 定义 的 过 滤器 



































定义 好 过 滤器 之 后 ， 要 使 用 Library 实例 注册 ,让 Django 的 模板 语言 知道 它 的 存在 : 





register.filter('cut', cut) 
register.filter('lower', Lower) 


Library.filter() 有 两 个 参数 : 


1， 过 滤器 的 名 称 ， 一 个 字符 串 。 
2， 负 责 处 理 过 滤器 的 函数 ， 一 个 Python 函数 〈 不 是 函数 名 称 的 字符 虽 





register.filter() 也 可 以 作为 装饰 器 使 用 : 


@register.filter(name='cut') 
def cut(vaLue，arg) : 

return value.replace(arg, '') 
@register.filter 
def lower(value): 

return value.lower() 


形式 ) 。 





最 好 还 是 抛 出 异 


如 果 不 指定 name 参数 ， 如 上 面 的 第 二 个 示例 ，Django 使 用 函数 的 名 称 作为 过 滤器 的 名 称 。 最 后 ，regis- 


ter.filter() 还 接受 三 个 关键 字 参 数 : is_safe、needs_autoescape 和 expects_localtime。 


器 和 自动 转 义 ?和 "“ 过 滤器 和 时 区 ”两 节 说 明 。 














这 些 参数 在 "过 涯 
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期 待 字 符 串 的 模板 过 滤器 


如 果 模 板 过 滤器 期 望 第 一 个 参数 是 字符 串 ， 应 该 使 用 stringfilter 装饰 器 。 这 样 ， 对 象 在 传 给 过 滤 器 之 前 会 
先 转换 成 字符 串 值 。 








from django import tempLate 
from django.template.defaultfilters import stringfilter 


register = template.Library() 
@register.filter 
@stringfilter 


def lower(value): 
return value.lower() 


这 里 ， 可 以 把 整数 传 给 过 滤器 ， 不 会 抛 出 AttributeError (因为 整数 没有 Lower() 方法 ) 。 


过 滤器 和 自动 转 义 


自 定 义 过 滤器 时 ， 应 该 想 想 Django 的 自动 转 义 行 为 对 过 滤器 有 什么 影响 。 注 意 ， 模 板 代 码 中 存在 三 种 字符 
串 : 








。 原始 字符 串 是 原生 的 Python str 或 unicode 类 型 。 输 出 时 ， 如 果 启 用 了 自动 转 义 就 转 义 ， 否则 原封 不 
动 呈 现 出 来 。 

。 安全 字符 串 是 标记 为 安全 的 字符 串 ， 输 出 时 不 会 转 义 ， 因 为 已 经 做 了 必要 的 转 义 。 在 客户 端 需要 原封 
不 动 输出 原始 HTML 时 经 常 使 用 这 种 字符 串 。 

在 内 部 ， 这 种 字符 串 是 SafeBytes 或 SafeText 类 型 。 二 者 的 共同 基 类 是 SafeData， 因 此 可 以 使 用 类 似 

下 面 的 代码 测试 : 










































































if isinstance(value, SafeData): 


# 对 “安全 的 ”字符 串 做 些 处 理 





。 标记 为 “需要 转 义 ”的 字符 串 是 在 输出 时 始终 应 该 转 义 的 字符 串 ， 不 管 在 不 在 autoescape 块 中 都 是 如 
此 。 然 而 ， 即 使 启用 了 自动 转 义 ， 这 种 字符 串 也 只 转 义 一 次 。 在 内 部 ， 这 种 字符 串 是 EscapeBytes 或 
EscapeText 类 型 。 一 般 情 况 下 ， 无 需 关 注 这 种 类 型 ， 它 们 只 在 escape 过 滤器 的 实现 中 存在 。 












































模板 过 滤器 分 属 两 种 情况 : 








1. 不 在 尚未 呈现 的 结果 中 引入 对 HTML 不 安全 的 字符 (<、>、'、" 或 8) 。 
2. 过 滤器 代码 自行 负责 做 必要 的 转 义 。 在 结果 中 引入 新 的 HTML 标记 时 必须 这 么 做 。 











对 第 一 种 情况 来 说 ， 可 以 交 给 Django 的 自动 转 义 行为 处 理 。 你 只 需 在 注册 过 滤器 函数 时 把 is_safe 旗 标 设 为 
True， 如 下 所 示 : 

















@register.filter(is_ safe=True) 
def myfilter(value): 
return value 


这 个 旗 标 告诉 Django， 如 果 传 人 过 滤器 的 是 “安全 "字符 串 ， 结 果 仍 是 “安全 的 ”。 而 如 果 传 人 不 安全 的 字符 
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串 ， 必 要 时 Django 会 自动 转 义 。 你 可 以 把 它 的 作用 理解 为 “这 个 过 滤器 是 安全 的 ， 不 会 引入 任何 不 安全 的 


HTML”, 











is_safe 的 存在 是 有 原因 的 ， 因 为 有 相当 多 的 字符 串 操 作 会 把 safeData 对 象 变 回 普通 的 str 或 unicode 对 























象 ， 而 捕获 所 有 情况 十 分 困难 ，Django 会 在 过 滤器 执行 完毕 后 修复 损伤 。 
假如 有 个 过 滤器 在 输入 后 面 添 加 字符 串 'xx' ， 因 为 没有 为 结果 (除了 已 经 呈现 的 ) 引入 危险 的 HTML 字符 ， 
































所 以 应 该 使 用 is_safe 标记 过 滤器 : 


@register.filter(is_safe=True) 
def add xx(value): 
return '%sxx' % value 





在 启用 自动 转 义 的 模板 中 使 用 这 个 过 滤器 时 ，Django 会 转 义 未 标记 为 “安全 ”的 输入 。is_safe 默认 为 False， 
因此 不 需要 标记 为 安全 的 过 滤器 可 以 省 略 这 个 旗 标 。 一 定 要 谨慎 ， 确 保安 全 的 字符 串 真 的 是 安全 的 。 注 意 ， 

















删除 字符 时 可 能 无 意 中 在 结果 中 留 下 错乱 的 HTML 标签 或 实体 。 





















































例如 ， 删 除 > 后 可 能 导致 输出 中 的 <a> 变 成 <a， 此 时 为 了 避免 出 问题 ， 应 该 转 义 输出 。 类 似 地 ， 删 除 分 号 














(;) 可 能 导致 &amp; 变 成 &amp， 这 不 是 有 效 的 HTML 实体 ， 应 该 转 义 。 多 数 情况 下 不 会 这 么 麻烦 ， 但 是 审 








查 代 码 时 要 留意 一 下 。 


把 过 滤器 标记 为 "安全 的 "之 后 ， 过 滤器 返回 的 值 会 强制 转换 成 字符 串 。 如 果 过 滤器 返回 布尔 值 或 其 他 字符 串 





之 外 的 值 ， 标 记 为 安全 可 能 导致 意料 之 外 的 后 果 (例如 把 布尔 





第 二 种 情况 没有 把 输出 标记 为 安全 的 ，HTML 标记 不 会 转 义 ， 
全 的 字符 串 ， 使 用 django.utils.safestring.mark_safe()。 




















值 False 转换 成 字符 串 'FaLse' ) 。 
因此 你 要 自己 动手 处 理 。 若 想 把 输出 标记 为 安 





























不 过 要 小 心 ， 你 要 做 的 不 仅 是 把 输出 标记 为 安全 的 ， 而 要 确保 输出 真 的 是 安全 的 。 此 时 ， 具 体 怎么 做 取决 于 








9 没有 启用 自动 转 义 。 















































编写 过 滤器 时 要 确保 不 管 有 没有 启用 自动 转 义 都 能 在 模板 中 正常 使 用 ， 从 而 解放 模板 编写 人 员 。 




















为 了 让 过 滤器 知道 当前 的 自动 转 义 状态 ， 注 册 过 滤器 函数 时 把 

















needs_autoescape 旗 标 设 为 True。 (如 果 不 指 


定 ， 这 个 旗 标 默认 为 False。) 这 个 旗 标 告诉 Djiango， 你 的 过 滤器 函数 要 传人 一 个 额外 的 关键 字 参 数 ， 名 为 

















autoescape， 在 启用 自动 转 义 时 值 为 True， 否则 为 False。 


例如 ， 下 述 过 滤器 突出 显示 字符 串 的 第 一 个 字符 : 

















from django import template 
from django.utils.html import conditional_escape 
from django.utils.safestring import mark_safe 


register = template.Library() 


Qregister.filter(needs_autoescape=True) 
def initial letter filter(text, autoescape=None): 
first, other = text[0], text[1:] 
if autoescape: 
esc = conditional_escape 
else: 


esc = lambda x: x 


result = '<strong>%s</strong>%s' % (esc(first), esc(other)) 


return mark_safe(result) 





我 们 指定 了 needs_autoescape 旗 标 和 autoescape 关键 字 参 数 ， 


因此 调用 这 个 过 滤器 时 知道 有 没有 启用 自动 转 
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义 。 我 们 通过 autoescape 判断 要 不 要 把 输入 数据 传 给 django.utils.html.conditional_escape。 (在 后 一 种 
情况 下 ， 直 接 把 函数 自身 当做 “ 转 义 ”函数 。) 











conditional_escape() 函数 的 作用 与 escape() 类 似 ， 不 过 它 只 转 义 不 是 SafeData 实例 的 输入 。 如 果 把 Safe- 
Data 实例 传 给 conditional_escape()， 数 据 原封 不 动 地 返回 。 





最 后 ， 在 上 述 示例 中 ， 我 们 把 结果 标记 为 安全 的 ， 因 此 HTML 直接 插入 模板 ， 不 再 转 义 。 这 里 无 需 担 心 
is_safe 旗 标 (不 过 加 上 也 没什么 损失 ) 。 只 要 自行 处 理 了 自动 转 义 问题 ， 返 回 安全 的 字符 串 ，ts_safe 旗 标 
就 不 会 再 做 处 理 。 














过 滤器 和 时 区 





自 定 义 处 理 datetime 对 象 的 过 滤器 时 ， 注 册 时 通常 要 把 expects_LocatLtime 旗 标 设 为 True: 


Qregister.fiLLter(expects_LocaLtime=True) 
def businesshours(vaLue) : 
TV 
return 9 <= vaLue.hour < 17 
except AttributeError : 


return 


这 样 设 定之 后 ， 如 果 过 滤器 的 第 一 个 参数 是 涉及 时 区 的 日 期 时 间 ， 根 据 模板 中 的 时 区 转换 规则 ， 必 要 时 
Django 会 先 把 它 转换 成 当前 时 区 ， 然 后 再 传 给 过 滤器 。 


复 用 内 置 过 滤器 时 避免 XSS 漏洞 





复 用 Django 内 置 的 过 滤器 时 要 小 心 ， 要 把 autoescape=True 传 给 过 滤器 ， 获 得 正确 的 自动 转 义 
行为 ， 并 且 避 免 跨 站 脚本 漏洞 。 假 如 你 想 编 写 一 个 urlize_and_linebreaks 过 滤器 ， 把 urlize 
和 Linebreaksbr 两 个 过 滤器 的 功能 合并 到 一 起 ， 应 该 这 么 编写 : 

















from django.template.defaultfilters import linebreaksbr, urlize 


@register.filter 
def urlize_and_linebreaks(text): 
return linebreaksbr(urlize(text, autoescape=True), autoescape=True) 


这 样 ，{{ comment|urlize_and_linebreaks }} 等 效 于 {{ comment|urlize|linebreaksbr }}。 


8.7.2 自 定义 模板 标签 





标签 能 做 任何 事情 ， 比 过 滤器 复杂 。Django 提供 了 一 些 快捷 方式 ， 简 化 了 多 数 标签 类 型 的 编写 。 首 先 ， 我 们 
将 探讨 这 些 快 捷 方 式 ， 然 后 说 明 在 快捷 方式 不 够 用 时 如 何 从 头 开始 编写 标签 。 
































简单 的 标签 


很 多 模板 标签 接受 几 个 参数 (字符 串 或 模板 变量 ) ， 对 输入 参数 和 一 些 外 部 信息 做 些 处 理 之 后 返回 一 个 结 
果 。 





例如 有 个 current_time 标签 ， 它 接受 一 个 格式 字符 串 ， 返 回 格式 化 后 的 时 间 字 符 串 。 为 了 简化 这 种 标签 的 创 
建 ，Django 提供 了 一 个 辅助 函数 ，simple_tag。 它 是 django.template.Library 中 的 一 个 方法 ， 其 参数 是 一 个 
接受 任意 个 参数 的 函数 ， 把 它 包装 在 render 函数 中 之 后 ， 再 做 些 前 述 的 必要 处 理 ， 最 后 注册 到 模板 系统 中 。 
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据 此 ，current_time 消 数 可 以 这 么 编写 .: 


import datetime 
from django import template 


register = template.Library() 
@register.simple tag 


def current_time(format_string): 
return datetime.datetime.now().strftime(format_string) 





关于 simple_tag 辅助 函数 有 几 点 要 注意 : 














。 调用 标签 函数 时 已 经 检查 了 必要 参数 的 数量 ， 因 此 无 需 我 们 检查 。 
。 参数 两 侧 的 引号 (如果 有 的 话 ) 已 经 去 掉 了 ， 接 收 到 的 是 普通 的 字符 串 。 
。 如 果 参 数 是 模板 变量 ， 传 给 标签 函数 的 是 变量 的 当前 值 ， 而 不 是 变量 本 身 。 

















0 











如 果 模 板 标签 需要 访问 当前 上 下 文 ， 注 册 标 签 时 指定 takes_context 参数 : 


@register.simple_tag(takes_context=True) 
def current_time(context, format_string): 
timezone = context['timezone'] 
return your_get_current_time method(timezone, format_string) 





意 ， 第 一 个 参数 的 名 称 必须 是 context。takes_context 选项 的 工作 机 制 参见 “引入 标签 ">。 如 果 想 为 标签 起 
个 别 的 名 称 ， 指 定 nane 参数 ， 








register.simple tag(lambda x: x - 1, name='minusone') 


@register.simple_ tag(name='minustwo') 
def some_function(vaLue) : 
return value - 2 


使 用 simple_tag 装饰 的 函数 可 以 接受 任意 个 位 置 参 数 和 关键 字 参 数 。 例 如 : 





@register.simple_ tag 

def my_tag(a, b, *args, **kwargs): 
warning = kwargs['warning'] 
profile = kwargs['profile'] 


return ... 

















然后 在 模板 中 可 以 把 任意 个 参数 (以 空格 分 开 ) 传 给 这 个 标签 。 与 Python 代码 一 样 ， 关 键 字 参 数 的 值 使 用 等 
号 (=) 设 定 ， 而 且 必 须 放 在 位 置 参数 后 面 。 例 如 




















{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %} 


引入 标签 














男 一 种 常见 的 模板 标签 用 于 演 染 男 一 个 模板 。 例 如 ，Django 的 管理 后 台 使 用 Bt ein 
面 下 部 显示 一 些 按钮 。 这 些 按钮 的 外 观 相 同 ， 但 是 链接 目标 根据 所 编辑 的 对 象 有 所 不 同 。 因 此 ， 这 些 按钮 特 
别 适 合 做 成 一 个 小 模板 ， 然 后 使 用 当前 对 象 填充 细节 。 (管理 后 台 使 用 的 是 submit_row 标签 。) 


这 种 标签 叫做 引入 标签 (inclusion tag) 。 这 种 标签 最 好 通过 实例 说 明 。 下 面 我 们 来 编写 一 个 标签 ， 生 成 指定 
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Author 对 象 名 下 的 图 书 列表 。 我 们 将 像 这 样 使 用 这 个 标签: 











{% books_for_author author %} 





得 到 的 结果 如 下 : 


<ul> 
<li>The Cat In The Hat</li> 
<li>Hop On Pop</\i> 
<li>Green Eggs And Ham</li> 
</ul> 

















首先 ， 要 定义 一 个 接受 参数 的 函数 ， 生 成 一 个 字典 ， 为 结果 提供 数据 。 注 意 ， 我 们 只 需 返 回 一 个 字典 ， 而 不 
是 其 他 复杂 的 数据 结构 。 返 回 的 字典 在 模板 片段 的 上 下 文中 使 用 。 

















def books_for_author(author ) : 
books = Book.objects.filter(authors__id=author .id) 
return {'books': books} 











然后 ， 创 建 用 于 演 染 标签 输出 的 模板 。 对 这 个 标签 来 说 ， 模 板 十 分 简单 : 








<UL> 

{% for book in books %} 
<li>{{ book.title }}</li> 

{% endfor %} 

</ul> 





最 后 ， 在 Library 对 象 上 调用 inclusion_tag() 方法 ,创建 并 注册 这 个 引入 标签 。 这 里 ， 如 果 上 述 模 板 保存 在 
模板 加 载 器 能 搜索 到 的 一 个 目录 中 ， 而 且 那 个 文件 名 为 book_snippet.html， 我 们 可 以 使 用 下 述 代码 注册 这 个 
标签 : 





























# 与 前 面 一 样 ， 这 里 的 register 是 django.template.Library 实例 
@register .inclusion tag('book_snippet.html') 
def show_reviews(review): 


此 外 ， 还 可 以 在 创建 这 个 函数 时 使 用 django.template.Template 实例 注册 引入 标签 : 


from django.template. loader import get_template 
t = get_ template('book_snippet.html') 
register.inclusion tag(t)(show_reviews) 














时， 引入 标签 可 能 需要 大 量 参 数 ， 导 致 模板 编写 人 要 记 住 所 需 的 参数 及 其 顺序 。 为 了 避免 这 种 痛苦 ，Djan- 
g0 为 引入 标签 提供 了 takes_context 选项 。 如 果 在 创建 引入 标签 时 指定 了 这 个 选项 ， 标 签 就 没有 必须 的 参数 
了 ， 底 层 的 Python 函数 只 有 一 个 参数 一 一 调用 标签 时 的 模板 上 下 文 。 假 如 你 编写 的 一 个 引入 标签 始终 在 包含 
home_link 和 home_titte 变量 的 上 下 文中 使 用 ， 用 于 指向 主页 。 此 时 ，Python 函数 可 以 这 样 编写 : 

































































@register.inclusion_tag('link.html', takes_context=True) 
def jump_link(context): 
return { 
'Link' : context['home_link'], 
'title': context['home title'], 
} 





意 ， 函 数 的 第 一 个 参数 必须 名 为 context。) tink.html 模板 可 能 包含 下 述 内 


蝶 
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Jump directly to <a href="{{ link }}">{{ title }}</a>. 





想 使 用 这 个 自 定义 标签 时 ， 只 需 加 载 所 在 的 库 ， 然 后 不 传人 参数 调用 ， 如 下 所 示 : 








{% jump_Link %} 


注意 ， 指 定 了 takes_context=True 之 后 ， 无 需 再 向 模板 标签 传递 参数 ， 它 始终 能 访问 上 下 文 。takes_context 
参数 的 默认 值 是 FaLse。 设 为 True 时 ， 把 上 下 文 对 象 传 给 标签 ， 如 上 例 所 示 。 这 个 示例 与 前 面 那个 示例 唯一 
的 区 别 就 在 这 里 。 与 简单 标签 一 样 ， 引 入 标签 函数 也 可 以 接受 任意 个 位 置 参 数 或 关键 字 参 数 。 

































































赋值 标签 














为 了 简化 创建 为 上 下 文中 的 变量 设 值 的 标签 ，Django 提供 了 一 个 辅助 函数 ， 名 为 asstgnment_tag。 这 个 函数 
的 作用 与 simple_tag() 类 似 ， 不 过 标签 的 结果 存储 在 指定 的 上 下 文 变量 中 ， 而 不 直接 输出 。 前 面 所 举 的 cur- 
rent_time 阴 数 可 以 改写 成 这 样 : 
























































@register.assignment_tag 
def get_current_time(format_string) : 
return datetime.datetime.now().strftime(format_string) 





























在 模板 中 ， 可 以 使 用 as 参数 把 结果 存储 在 一 个 变量 中 ， 然 后 在 适合 的 地 方 输出 : 


{% get_current time "%Y-%m-%d %I:%M %p" as the_ time %} 
<p>The time is {{ the_time }}.</p> 


8.8 自 定义 模板 标签 的 高 级 方式 


9 时， 这 些 自 定义 模板 标签 的 方式 不 够 用 。 为 了 让 你 能 从 头 开 始 构 建 模 板 标 签 ，Django 提供 了 模板 系统 的 完 
整 内 部 细节 。 

















8.8.1 概览 





模板 系统 的 运作 分 为 两 步 : 编译 和 泻 染 。 因 此 ， 自 定义 模板 要 指定 如 何 编译 和 泻 染 。Django 编译 模板 时 ， 把 
原始 模板 分 解 为 一 个 个 “节点 *。 节 点 是 django.tempLate.Node 实例 ， 有 一 个 render() 方法 。 编 译 好 的 模板 其 
实 就 是 一 些 Node 对 象 。 






































在 编译 好 的 模板 对 象 上 调用 render() 方法 时 ， 模 板 在 节点 列表 中 的 各 个 Node 对 象 上 调用 render() 方法 ， 并 
传人 指定 的 上 下 文 。 最 后 ， 把 各 个 节点 的 输出 拼接 在 一 起 ， 组 成 模板 的 输出 。 因 此 ， 自 定义 模板 标签 时 ， 要 
指定 如 何 把 原始 模板 转换 成 Node 对 象 (编译 ) ， 并 且 指 定 节点 的 render() 方法 要 做 什么 ( 泻 染 ) 。 


























8.8.2 编写 编译 函数 





模板 解析 器 遇 到 模板 标签 时 ， 调 用 一 个 Python 函数 ， 并 且 传 人 标签 的 内 容 和 解析 器 对 象 自 身 。 这 个 函数 负责 
根据 标签 的 内 容 返 回 一 个 Node 实例 。 下 面 我 们 将 从 头 开始 实现 前 面 那个 简单 的 模板 标签 { current_time 
9J， 根 据 参 数 中 以 strftime() 句法 指定 的 格式 显示 当前 日 期 和 时 间 。 开 始 行动 之 前 ， 最 好 确定 标签 的 句法 。 
这 里 ,假设 将 像 下 面 这 样 使 用 这 个 标签 : 







































































<p>The time is {% current_ time "%Y-%m-%d %I:%M %p" %}.</p> 





这 个 函数 的 解析 器 应 该 获取 参数 ， 然 后 创建 一 个 Node 对 象 : 











from django import tempLate 
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def do_current_time(parser，token) : 


站 Ty 
tag_name, format_string = token.split_contents() 
except ValueError: 
raise template.TemplateSyntaxError("%r tag requires a single argument" 
% token.contents.split()[0]) 


if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")): 
raise template.TemplateSyntaxError("%r tag's argument should be in quotes" 
% tag_name) 
return CurrentTimeNode(format_string[1:-1]) 


parser 是 模板 解析 器 对 象 。 这 里 用 不 到 。 


p= 


token.contents 是 标签 的 原始 内 容 字 符 串 。 这 里 是 'current_time "%Y-%m-%d %I:%M %p"'。 


token.split_contents() 在 空格 处 把 标签 的 名 称 和 参数 分 开 ， 不 过 放 在 引号 内 的 字符 串 保 持 不 动 。to- 
ken.contents.split() 简单 一 些 ， 但 是 不 够 可 靠 ， 它 会 在 所 有 空格 处 拆 分 ， 包 括 引号 内 的 空格 。 最 好 
始终 使 用 token.spLit_contents()。 

遇 到 句法 错误 时 ， 这 个 函数 会 抛 出 django.tempLate.TempLateSyntaxError， 并 且 提供 有 用 的 消息 。 
TempLateSyntaxError 异常 用 到 了 tag_name 变量 。 别 在 错误 消息 中 硬 编 码 标签 的 名 称 ， 避 免 标签 的 名 
称 与 函数 耦合 。token.contents.sptLit()[9] 的 值 始 终 是 标签 的 名 称 ， 即 使 标签 没有 参数 。 

这 个 函数 返回 一 个 CurrentTimeNode 对 象 ， 它 具有 节点 需要 知道 的 关于 这 个 标签 的 一 切 信息 。 这 里 ， 
它 知道 的 是 "%Y-%m-%d %I:%M %p"。format_string[1:-1] 把 标签 参数 两 侧 的 引号 去 掉 。 

解析 是 非常 低层 的 操作 。Django 的 开发 者 试 过 以 这 个 解析 系统 为 基础 编写 一 个 小 框架 ,使 用 EBNF 语 
法 等 技术 ,但 是 结果 发 现 模板 引擎 速度 太 慢 。 放 在 低层 是 因为 那里 速度 最 快 。 













































































8.8.3 编写 泻 染 器 











自 定义 标签 的 第 二 步 是 定义 一 个 具有 render() 方法 的 Node 子 类 。 接 着 上 面 的 示例 ， 我 们 要 定义 CurrentTi- 











meNode 类 ， 


import datetime 


from django import template 


class CurrentTimeNode(template.Node): 


def _init_ (self, format_string): 
self.format_string = format_string 


def render(self, context): 
return datetime.datetime.now().strftime(self.format_string) 


__init _() 从 do_current_time() 中 获取 format_string。 节 点 的 选项 或 参数 都 通过 __init_() 传递 。 
具体 的 工作 在 render() 方法 中 做 。 


一 般 来 说 ，render() 应 该 静默 问题 ， 尤 其 是 在 DEBUG 和 TEMPLATE_DEBUG 设 为 False 的 生产 环境 。 然 
而 ， 有 些 情况 下 ， 尤 其 是 TEMPLATE_DEBUG 设 为 True 时 ，render() 方法 可 以 抛 出 异常 ， 以 便 调试 。 例 
如 ， 有 几 个 内 置 的 标签 在 收 到 错误 的 参数 数量 或 类 型 时 抛 出 django.tempLate.TempLateSyntaxError。 
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这 种 编译 和 演 染 的 解 耦 得 到 的 是 高 效 的 模板 系统 ， 因 为 无 需 多 次 解析 一 个 模板 就 可 以 泻 染 多 个 上 下 文 。 


8.8.4 自动 转 义 方面 的 注意 事项 


模板 标签 的 输出 不 会 自动 转 义 。 此 外 ， 编 写 模板 标签 时 还 有 几 件 事 要 留意 。 如 果 render() 方法 把 结果 存储 在 
上 下 文 变量 中 〈 而 不 是 返回 一 个 字符 串 ) ， 你 要 负责 在 适当 的 时 候 调 用 mark_safe()。 最 终 演 染 上 下 文 变 量 
时 ， 会 受到 彼 时 的 自动 转 义 状 态 影响 ， 因 此 无 需 进 一 步 转 义 的 安全 内 容 应 该 标记 为 安全 的 。 


此 外 ， 如 果 模 板 标签 创建 新 的 上 下 文 ， 用 于 执行 旁 支 泻 染 ， 要 把 自动 转 义 状态 设 为 当前 上 下 文中 的 值 。Con- 
text 类 的 _init “方法 有 个 名 为 autoescape 的 参数 ， 它 的 作用 就 是 如 此 。 例 如 : 


















































from django.template import Context 


def render(self, context): 
和 
new_context = Context({'var': obj}, autoescape=context.autoescape) 
处理 new_context ... 


这 种 情况 不 是 十 分 常见 ， 但 是 自己 泻 染 模板 时 用 得 到 。 例 如 : 











def render(self, context): 
= context.template.engine.get template('small_ fragment.html') 
return t.render(Context({'var': obj}, autoescape=context.autoescape)) 





这 里 ， 如 果 忘 了 把 context.autoescape 传 给 新 的 上 下 文 ， 结 果 始 终 会 被 转 义 ， 如 此 一 来 ， 在 {% autoescape 
off %} 块 中 的 行为 可 能 与 预期 不 符 。 





8.8.5 线程 安全 方面 的 注意 事项 


解析 节点 后 ， 可 能 在 节点 上 多 次 调用 render 方法 。Django 有 时 在 多 线程 环境 中 运行 ， 因 此 一 个 节点 可 能 
时 在 不 同 的 上 下 文中 泻 染 ， 啊 应 不 同 的 请 求 。 


鉴于 此 ， 一定 要 确保 模板 标签 是 线程 安全 的 。 为 此 ， 一 定 不 能 在 节点 中 存储 状态 信息 。 例 如 ，Django 提供 的 
内 置 模 板 标 签 cycle 遍历 指定 的 字符 串 列表 : 















































{% for o in some_list %} 
<tr class="{% cycle 'rowi' 'row2' %}> 


</tr> 
{% endfor %} 




















你 可 能 天 真 地 以 为 CycleNode 是 这 么 实 


党 
吾 


import itertools 
from django import template 


class CycleNode(template.Node): 
def init (self, cyclevars): 
self.cycle iter = itertools.cycle(cyclevars) 


def render(self, context): 
return next(self.cycle iter) 
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但 是 ， 假 设 有 两 个 模板 同时 泻 染 上 述 模板 片段 : 

















1， 线程 1 执行 第 一 次 迭代 ，CycleNode.render() 返回 'row1' 
2.， 线程 2 执行 第 一 次 迭代 ，CycleNode.render() 返回 'row2' 
3.， 线程 1 执行 第 二 次 迭代 ，CycleNode.render() 返回 'row1' 
4. 线程 2 执行 第 二 次 迭代 ，CycleNode.render() 返回 'row2' 
CycleNode 是 迭代 了 ， 但 却 是 全 局 迭代 的 ， 线 程 1 和 线程 2 各自 始终 返回 相同 的 值 。 这 显然 不 是 我 们 想 要 的 




















行为 ! 


为 了 解决 这 种 问题 ，Django 提供 了 与 当前 泻 染 的 模板 上 下 文 有 关 的 render_context。 它 的 行为 与 Python 字 
类 似 ， 用 于 存储 多 次 调用 render 方法 之 间 的 节点 状态 。 下 面 使 用 render_context 重 构 CycleNode 类 . 




















人 己 



































class CycleNode(template.Node): 
def _ init (self, cyclevars): 
self.cyclevars = cyclevars 


def render(self, context): 
if self not in context.render_context: 
context.render_context[self] = itertools.cycle(self.cyclevars) 
cycle_iter = context.render_context[self] 
return next(cycle iter) 





注意 ， 完 全 可 以 把 节点 的 生命 周期 内 不 会 变化 的 全 局 信息 存储 为 一 个 属性 。 


























对 这 里 的 CycleNode 类 来 说 ， Et 参数 在 节点 实例 化 之 后 就 不 变 了 ， 因 此 不 用 放 到 render_context 里 
但 是 ， 针 对 当前 泻 染 模板 的 状态 信息 ， 例 如 CycleNode 当前 迭代 的 内 容 ， 应 该 存储 在 render_context 中 。 














o 











8.8.6 注册 标签 


最 后 ， 像 8.7.1 市 那 样 ， 使 用 模块 的 Library 实例 注册 标签 。 例 如 : 
register.tag('current time', do_current_ time) 


tag() 方法 有 两 个 参数 : 














1， 模 板 标签 的 名 称 ， 一 个 字符 串 。 如 果 留 空 ， 使 用 编译 函数 的 名 称 。 
2， 编 译 函数 ， 一 个 Python 函数 〈 不 是 函数 名 称 的 字符 串 形 式 ) 。 























与 注册 过 滤器 一 样 ， 这 个 方法 还 可 以 作为 装饰 器 使 用 : 





Qregister.tag(name="current_time") 
def do_current_time(parser, token): 


@register .tag 


def shout(parser, token): 





如 果 不 指定 name 参数 ， 如 上 面 的 第 二 个 示例 所 示 ，Django 将 使 用 函数 的 名 称 作 为 标签 的 名 称 。 
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8.8.7 把 模板 变量 传 给 标签 


里 然 可 以 把 任意 个 参数 传 给 模板 标签 ， 然后 使 用 token.split_contents() 分 拆 ， 但 是 参数 都 拆 包 成 字符 串 字 
i 量 。 如 果 想 通过 模板 标签 的 参数 传人 动态 内 容 (模板 变量 ) ， 要 做 些 额外 工作 。 


上 述 示例 把 当前 时 间 格 式 化 成 一 个 字符 串 ， 然 后 返回 那个 字符 串 。 假 如 我 们 想 传 入 DateTimeField 中 的 日 期 
时 间 对 象 ， 让 那个 模板 标签 格式 化 呢 : 








I 



































<p>This post was last updated at {% format time blog_ entry.date updated "%Y-%m-%d %I:%M %p" 
%}.</p> 


现在 ，token.split_contents() 返回 三 个 值 : 





1. 标签 的 名 称 format_time。 
2.， 字符 串 'blog_entry.date_updated' (没有 两 侧 的 引号 ) 。 
3. 格式 字符 串 '"%Y-%m-%d %I:%M %p"'。split_contents() 返回 的 值 中 包含 字符 串 字 








看 量 两 侧 的 引号 。 














因此 ， 标 签 要 像 下 面 这 样 定义 : 





from django import template 


def do_format_time(parser, token): 
GEV 
# split_contents() 不 会 分 拆 放 在 引号 里 的 字符 串 
tag_name, date_to_be_formatted, format_string = 
token.split_contents() 
except ValueError: 
raise template.TemplateSyntaxError("%r tag requires exactly 
two arguments" % token.contents.split()[0]) 
if not (format_string[0] == format_string[-1] and 
format_string[0] in ('"', "'")): 
raise template.TemplateSyntaxError("%r tag's argument should 
be in quotes" % tag_name) 
return FormatTimeNode(date_to_be_formatted, format_string[1:-1]) 


此 外 ， 还 要 修改 泻 染 器 ， 检 索 blog_entry 对 象 的 date_updated 属性 。 这 一 步 可 以 使 用 django.template 包 中 
的 Variable() 类 实现 。 


Variable() 类 的 用 法 很 简单 ， 先 使 用 变量 的 名 称 实例 化 ， 然 后 调用 variable.resolve(context)。 例 如 : 





class FormatTimeNode(template.Node): 
def _init (self, date_ to_be formatted, format_string): 
self.date_to_be_formatted = 
template.Variable(date_to_be_formatted) 
self.format_string = format_string 


def render(self, context): 
tr 
actual_date = self.date to_ be formatted.resolve(context) 
return actual_date.strftime(self.format_string) 
except template.VariableDoesNotExist: 


return 
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如 果 在 当前 上 下 文中 无 法 把 传人 的 字符 串 解 析 成 变量 ， 抛 出 VariableDoesNotExist 异常 。 








8.8.8 在 上 下 文中 设 定 变量 


上 述 示例 只 是 输出 值 。 一 般 来 说 ， 设 定 模板 变量 的 标签 比 输出 值 的 标签 更 灵活 。 这 样 ， 模 板 编写 人 便 可 以 复 
用 编码 标签 创建 的 值 。 若 想 在 上 下 文中 设 定 变量 ， 在 render() 方法 中 像 字典 那样 为 上 下 文中 的 变量 赋值 。 下 
面 是 CurrentTimeNode 的 更 新 版 本 ， 设 定 current_time 模板 变量 ， 而 不 输出 : 



























































import datetime 
from django import tempLate 


class CurrentTimeNode2(template.Node): 
def _init (self, format_string): 
self.format_string = format_string 
def render(self, context): 
context[ 'current_ time'] = 
datetime.datetime.now().strftime(self.format_string) 


return 





注意 ，render() 方法 返回 了 一 个 空 字符 串 。render() 始终 应 该 返回 一 个 字符 串 。 如 果 模 板 标签 只 设 定 变 
render() 应 该 返回 一 个 空 字符 串 。 这 个 新 版 本 的 用 法 如 下 : 


部 








{% current_time "%Y-%M-%d %I:%M %p'" %} 
<p>The time is {{ current_time }}.</p> 


上 下 文中 的 变量 作用 域 


上 下 文中 设 定 的 变量 只 在 设 定 它 的 模板 块 中 可 用 。 这 种 行为 是 故意 为 之 的 ， 目 的 是 为 变量 提供 一 个 作用 域 ， 
以 防 与 其 他 块 的 上 下 文 冲突 。 








但 是 ，CurrentTimeNode2 有 个 问题 : 变量 名 称 current_time 是 硬 编码 的 。 这 意味 着 ,模板 中 不 能 再 使 用 {{ 
current_time }}， 因 为 {% current_time %} 会 毫 不 客气 地 覆盖 那个 变量 的 值 。 








正确 的 做 法 是 让 模板 标签 指定 变量 的 名 称 ， 如 下 所 示 : 


{% current_time "%Y-%M-%d %I:%M %p" as my_current time %} 
<p>The current time is {{ my_current_ time }}.</p> 


为 此 ， 编 译 函数 和 Node 类 都 要 重 构 ， 如 下 所 示 : 





import re 


class CurrentTimeNode3(template.Node): 
def init (self, format_ string, var_name): 
self.format_string = format_string 
self.var_name = Var_name 
def render(self, context): 
context[self.var_name] = 
datetime.datetime.now().strftime(self.format_string) 


return 


def do_current_time(parser, token): 


# 这 一 版 使 用 正则 表达 式 解 析 标签 的 内 容 
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trv: 
# None 的 作用 相当 于 在 空格 处 分 拆 
tag_name，arg = token.contents.split(None, 1) 
except ValueError: 
raise template.TemplateSyntaxError("%r tag requires arguments" 
% token.contents.split()[0]) 
m= re.search(r'(.*?) as (\w+)', arg) 
if not m: 
raise template.TemplateSyntaxError("%r tag had invalid arguments" % tag_name) 
format_string, var_name = m.groups() 
if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")): 
raise template.TemplateSyntaxError("%r tag's argument should be in quotes" 
% tag_name) 
return CurrentTimeNode3(format_string[1:-1], var_name) 


这 一 版 不 同 的 地 方 是 ，do_current_time() 获取 的 格式 字符 串 和 变量 名 称 都 传 给 CurrentTimeNode3。 最 后 ， 如 
果 想 让 更 新 上 下 文 的 模板 标签 具有 简单 的 句法 ， 可 以 使 用 前 文 介绍 的 辅助 标签 。 





8.8.9 一 直 解 析 到 另 一 个 块 标签 


模板 标签 可 以 配对 。 例 如 ， 内 置 的 {% comment %} 标签 把 {% endcomment %} 之 前 的 内 容 都 隐藏 起 来 。 如 果 想 
创建 这 种 模板 标签 ， 在 编译 函数 中 使 用 parser .parse()。 下 面 是 {% comment %} 标签 的 简单 实现 : 






































def do_comment(parser, token): 
nodelist = parser.parse(('endcomment',)) 
parser.delete first_token() 
return CommentNode() 


class CommentNode(template.Node): 
def render(self, context): 


return 


{% comment %} 标签 的 真正 实现 方式 稍 有 不 同 ， 人 允许 {% comment %} 和 {% endcomment %} 之 间 有 
不 可 用 的 模板 标签 。 为 此 ，parser.delete_first_token() 前 面 调用 的 是 pars- 
er.skip_past('endcomment') ， 而 非 parser.parse(('endcomment',))， 以 免 生成 节点 列表 。 











parser .parse() 的 参数 是 一 个 元 组 ， 指 定 要 “解析 到 的 ” 块 标签 。 它 的 返回 值 是 一 个 django.tempLate.NodeList 
实例 ， 这 是 解析 器 在 遇 到 那个 元 组 中 的 标签 名 称 之 前 得 到 的 Node 对 象 列 表 。 对 上 述 示例 中 的 nodelist = 
parser.parse(('endcomment ' ,)) 来 说 ， 得 到 的 节点 列表 包含 {% comment %} 和 {% endcomment %} 之 间 的 所 有 
节点 ， 但 是 不 含 {% comment % 和 {% endcomment %} 自身 。 





调用 parser.parse() 之 后 ， 解 析 器 尚未 解析 { endcomment %} 标签 ， 因 此 要 调用 parser.delete first_to- 
ken()。CommentNode.render() 只 是 返回 一 个 空 字符 串 ， 即 {% comment %} 和 {% endcomment %} 之 间 的 一 切 都 


8.8.10 一 直 解 析 到 另 一 个 块 标签 ， 并 且 保 存 内 容 


在 上 述 示例 中 ，do_comment() 丢掉 {% comment %} 和 { endcomment %} 之 间 的 一 切 内 容 。 但 是 有 时 可 能 需要 
对 一 对 块 标签 中 的 内 容 做 些 处 理 。 例 如 ， 下 述 自 定义 模板 标签 {% upper 时 把 它 和 {% endupper 好 之 间 的 内 
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容 变 成 大 写 : 


{% upper %}This will appear in uppercase, {{ your_name }}.{% endupper %} 





与 前 面 的 示例 一 样 ， 我 们 要 使 用 parser.parse()。 但 是 这 一 次 要 把 得 到 的 节点 列表 传 给 Node 子 类 . 











def do_upper(parser, token): 
nodelist = parser.parse(('endupper',)) 
parser.delete first_token() 
return UpperNode(nodelist) 


class UpperNode(tempLate.Node) : 
def _init_ (self, nodelist): 
self.nodelist = nodelist 


def render(self, context): 
output = self.nodelist.render(context) 
return output.upper() 


这 里 只 有 一 处 新 内 容 : UpperNode.render() 中 的 self.nodelist.render(context)。 如 果 想 查找 复杂 泻 染 的 更 
多 示例 ， 请 看 django/template/defaulttags.py 中 {% for %} 标签 的 源码 ， 以 及 django/template/smartif.py 
中 {% if %) 标签 的 源码 。 





8.9 接 下 来 














下 一 章 继续 讨论 高 级 话题 ， 说 明 Django 模型 的 高 级 用 法 。 
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第 9 章 Django 模型 的 高 级 用 法 








第 4 章 介绍 了 Django 的 数据 库 层 ， 说 明了 如 何 定义 模型 ， 以 及 如 何 使 用 数据 库 API 创建 、 检 索 、 更 新 和 删 





除 记 录 。 本 章 将 介绍 Django 数据 库 层 的 一 些 高 级 特性 。 


9.1 相关 的 对 象 


我 们 在 第 4 章 定 义 了 下 面 几 个 模型 ; 





from django.db import models 


class Publisher(models.Model): 
name = models.CharField(max_length=30) 
address = models.CharField(max_length=50) 
city = models.CharField(max_length=60) 
state_province = models.CharField(max_length=30) 
country = models.CharField(max_length=50) 
website = models.URLField() 


def _str_(self): 
return self.name 


class Author(models.Model): 
first_name = models.CharField(max_length=30) 
Last_name = models.CharField(max_length=40) 
email = models.EmailField() 


def _ str_(self): 
return '%s %s' % (self.first name, self.Tlast_name) 


class Book(models.Model): 
title = models.CharField(max_length=100) 
authors = models.ManyToManyField(Author) 
publisher = models.ForeignKey(Publisher) 
publication_date = models.DateField() 


def _str__(self): 
return self.title 


我 们 知道 ， 访 问 数据 库 中 某 一 列 很 简单 ， 只 需 访 问 对 象 的 属性 。 例 如 ， 若 想 查 看 ID 为 50 的 
以 这 么 做 : 


>>> from mysite.books.models import Book 
>>> b = Book.objects.get(id=50) 

>>> b.title 

'The Django Book' 


图 书 的 书 名 ， 可 
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但 是 前 面 没有 指出 ， 相 关 的 对 象 (Foreignkey 或 ManyToManyField 字段 ) 行为 稍微 有 些 不 同 。 





9.1.1 访问 外 键 值 


访问 ForeignKey 类 型 的 字段 时 ， 得 到 的 是 相关 的 模型 对 象 。 例 如 : 


>>> b = Book.objects.get(id=50) 
>>> b.publisher 

<Publisher: Apress Publishing> 
>>> b.publisher .website 
'http://www.apress.com/' 

















ForeignKey 字段 也 能 反 向 使 用 ， 不 过 因为 关系 是 不 对 称 的 ， 行 为 稍 有 不 同 。 若 想 获取 指定 出 版 社 出 版 的 所 有 
图 书 ， 要 使 用 publisher .book_set.all()， 如 下 所 示 : 





>>> p = Publisher .objects.get(name='Apress Publishing') 
>>> p.book_set.all() 
[<Book: The Django Book>, <Book: Dive Into Python>, ...] 


其 实 ，book_set 就 是 一 个 QuerySet 对 象 (参见 第 4 章 ) ， 可 以 过 滤 和 切片 。 例 如 : 


>>> p = Publisher .objects.get(name='Apress Publishing') 
>>> p.book_set.filter(title icontains='django') 
[<Book: The Django Book>, <Book: Pro Django>] 


book_set 属性 是 生成 的 : 把 模型 名 的 小 写 形 式 与 _set 连 在 一 起 。 





9.1.2 访问 多 对 多 值 





多 对 多 什 与 外 键 值 的 获取 方式 类 似 ， 不 过 处 理 的 是 Queryset 值 ， 而 非 模 型 实例 。 例 如 ， 查 看 一 本 的 的 作者 要 
这 人 么 做 : 


>>> b = Book.objects.get(id=50) 

>>> b.authors.all() 

[<Author: Adrian Holovaty>, <Author: Jacob Kaplan-Moss>] 
>>> b.authors.filter(first_name='Adrian') 

[<Author: Adrian Holovaty>] 

>>> b.authors.filter(first_name='Adam') 


[] 
反 过 来 也 可 以 。 如 果 想 查看 一 位 作者 撰写 的 所 有 图 书 ， 使 用 author .book_set， 如 下 所 示 : 





>>> a = Author.objects.get(first_name='Adrian', 
last_name='Holovaty') 

>>> a.book_set.all() 

[<Book: The Django Book>, <Book: Adrian's Other Book>] 





与 ForeignKey 字段 一 样 ， 这 里 的 book_set 也 是 生成 的 ;把 模型 名 的 小 写 形式 与 _set 连 在 一 起 。 


9.2 管理 器 


在 Book.objects.all() 语句 中 ，objects 是 个 特殊 的 属性 ， 我 们 通过 它 查 询 数据 库 。 第 4 章 简单 说 过 ， 这 是 
模型 的 管理 器 (manager) 。 现 在 ,我们 要 深入 说 明 管 理 器 的 作用 和 用 法 。 
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简单 来 说 ， 模 型 的 管理 器 是 Django 模型 用 于 执行 数据 库 查 询 的 对 象 。 一 个 Django 模型 至 少 有 一 个 管理 器 ， 
而 且 可 以 自 定义 管理 器 ， 定 制 访问 数据 库 的 方式 。 自 定义 管理 器 可 能 出 于 两 方面 的 原因 : 添加 额外 的 管理 器 
方法 和 (或 ) 修改 管理 器 返回 的 QuerySet。 
























































9.2.1 添加 额外 的 管理 器 方法 


添加 额外 的 管理 器 方法 是 为 模型 添加 数据 表层 功能 的 首选 方式 。 (数据 行 层 的 功能 ， 即 在 模型 对 象 的 单个 实 
例 上 执行 的 操作 ， 使 用 模型 方法 。 本 章 后 面 将 做 说 明 。) 


举 个 例子 。 下 面 我 们 为 Book 模型 添加 一 个 管理 需 方 法 titte_count()， 它 的 参数 是 一 个 关键 字 ， 返 回 书 名 中 
包含 关键 字 的 图 书 数量 。 (这 个 示例 是 故意 设计 出 来 的 ， 不 过 能 说 明 管理 器 的 运作 方式 。) 















































# models.py 
from django.db import models 
# ... Author 和 Publisher 模型 省 略 了 ... 


class BookManager(modeLs.Manager ) : 
def title count(self, keyword): 
return self.filter(title icontains=keyword).count() 


class Book(models.Model): 
title = models.CharField(max_length=100) 
authors = models.ManyToManyField(Author) 
publisher = models.ForeignKey(Publisher) 
publication date = modeLs.DateFieLd() 
num_pages = models.IntegerField(blank=True, null=True) 
objects = BookManager() 


def _ str__(self): 
return self.title 


这 段 代码 有 几 点 需要 注意 : 
1. 我 们 定义 的 BookManager 类 扩展 django.db.models.Manager。 类 中 只 有 一 个 方法 ，title_count(),， 做 相 
关 的 计算 。 注 意 ， 这 个 方法 使 用 了 self.filter()， 其 中 self 指 代 管理 器 自身 。 


2， 我 们 把 BookManager() 赋值 给 模型 的 objects 属性 。 这 么 做 的 效果 是 替换 模型 的 "默认 ”管理 器 ， 即 未 指 
定 管理 器 时 自动 创建 的 objects。 我 们 仍 把 它 叫 做 objects， 以 便 与 自动 创建 的 管理 器 保持 一 致 。 






































创建 好 管理 器 之 后 ， 可 以 像 下 面 这 样 使 用 : 





>>> Book.objects.titLe_count('django ' ) 
4 
>>> Book.objects.titLe_count('python ' ) 
18 


显然 ， 这 只 是 示例 ， 如 果 你 在 自己 的 交互 式 解释 器 中 输入 上 述 代码 ， 得 到 的 返回 值 可 能 不 同 。 








我 们 为 什么 想 要 添加 title_count() 这 样 的 方法 呢 ? 为 的 是 封装 经 常 执 行 的 查询 ， 以 免 代码 重复 。 
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9.2.2 修改 管理 器 返回 的 查询 集合 








管理 器 的 基本 查询 集合 返回 系统 中 的 所 有 对 象 。 例 如 ，Book.objects.all() 返回 数据 库 中 的 所 有 图 书 。 若 想 
覆盖 管理 器 的 基本 查询 集合 ， 覆 盖 Manager .get_queryset() 方法 。get_queryset() 方法 应 该 返回 一 个 Query- 
set， 包含 所 需 的 属性 。 


例如 ， 下 述 模型 有 两 个 管理 器 ， 一 个 返回 所 有 对 象 ， 另 一 个 只 返回 Roald Dahl 写 的 书 。 




















from django.db import models 


# 首先 ， 定 义 Manager 子 类 
class DahlBookManager (models .Manager ) : 
def get_queryset(self): 
return super(DahlBookManager, self).get_ queryset().filter(author='Roald Dahl') 


# 然后 ， 放 入 Book 模型 

class Book(models.Model): 
title = models.CharField(max_length=100) 
author = models.CharField(max_length=50) 
和 


objects = models.Manager() # 默认 的 管理 器 
dahl_objects = DahlBookManager() # 专门 查询 Dahl 的 管理 器 


对 这 个 示例 模型 来 说 ，Book.objects.all() 返回 数据 库 中 的 所 有 图 书 ， 而 Book.dahl_objects.all() 只 返回 
Roald Dahl 写 的 书 。 注 意 ， 我 们 明确 地 把 objects 设 为 一 个 普通 的 Manager 示例 ， 如 若 不 然 ， 唯 一 可 用 的 管理 
器 将 是 dahL_objects。 当 然 ，get_queryset() 返回 的 是 一 个 Queryset 对 象 ， 因 此 可 以 在 其 上 调用 filter()、 
exclude() 和 其 他 所 有 QuerySet 支持 的 方法 。 所 以 ， 下 述 语句 都 是 有 效 的 : 






































Book.dahl_objects.all() 
Book.dahl_objects.filter(title='Matilda') 
Book.dahl_objects .count() 





这 个 示例 还 指出 了 另 一 个 有 用 的 技术 : 在 同一 个 模型 上 使 用 多 个 管理 器 。 只 要 需要 ， 可 以 为 模型 添加 任意 个 
Manager() 实例 。 这 么 做 ， 可 以 轻易 为 模型 定义 常用 的 “过 滤器 "。 例 如 : 











class MaLeManager(modeLs.Manager ) : 
def get queryset(self): 
return super(MaleManager, self).get queryset().filter(sex='M') 


class FemaleManager(models .Manager ) : 
def get_queryset(seLf ) : 
return super(FemaleManager, self).get queryset().filter(sex='F') 


class Person(models.Model): 
first_name = models.CharField(max_length=50) 
Last_name = models.CharField(max_length=50) 
sex = models.CharField(max_length=1, 
choices=( 
('M', 'Male'), 
('F', 'Female') 
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people = models.Manager() 
men = MaleManager() 
women = FemaleManager() 


这 样 定 义 之 后 ， 可 以 使 用 Person.men.all()、Person.women.all() 和 Person.people.all()， 而 且 能 得 到 预期 





的 结果 。 自 定义 Manager 对 象 时 要 注意 ，Django 遇 到 的 第 一 个 管理 器 (按照 在 模型 中 定义 的 顺 





齐 ) 有 特殊 的 











状态 。Django 把 它 解释 的 第 一 个 管理 器 定义 为 "默认 的 ”管理 器 ， 而 且 Django 在 很 多 地 方 (管理 
列 ) 只 使 用 那个 管理 器 。 


鉴于 此 ， 通 常 最 好 小 心 选择 默认 的 管理 器 ， 以 防 把 get_queryset() 返回 的 结果 覆盖 掉 ， 无 法 检 
象 。 
































9.3 模型 方法 





后 台 不 在 此 


索 所 需 的 对 


模型 中 自 定义 的 方法 为 对 象 添 加 数据 行 层 的 功能 。 管 理 器 的 作用 是 执行 数据 表层 的 操作 ， 而 模型 方法 处 理 的 





是 具体 的 模型 实例 。 这 个 技术 的 价值 很 大 ， 能 把 业务 逻辑 统一 放 在 一 个 地 方 ， 即 模型 中 。 
通过 示例 说 明 最 简单 。 下 述 模型 有 一 个 自 定义 的 方法 : 














from django.db import models 


class Person(modeLs .ModeL) : 
first_name = models.CharField(max_length=50) 
Last_name = models.CharField(max_length=50) 
birth_date = models.DateField() 


def baby_boomer_status(self): 

# 返回 一 个 人 的 出 生日 期 与 婴儿 潮 的 关系 

import datetime 

if self.birth date < datetime.date(1945, 8, 1): 
return "Pre-boomer" 

elif self.birth date < datetime.date(1965, 1, 1): 
return "Baby boomer" 

else: 
return "Post-boomer" 


def get full name(self): 
# 返回 一 个 人 的 全 名 


return '%s %s' % (self.first name, self.last _ name) 


full_name = property(_get_full_name) 





各 个 模型 自动 具有 的 方法 列表 参见 附录 A。 这 些 方法 基本 上 都 可 以 覆盖 (参见 下 文 ) ， 其 中 几 个 最 常 定义 : 











。 __str_()。 这 是 Python 的 一 个 “魔法 方法 "， 返 回 对 象 的 Unicode 表示 形式 。 需 要 以 普通 的 字符 串 显 示 
































模型 实例 时 ，Python 和 Django 会 调用 这 个 方法 。 尤 其 要 注意 ， 在 交互 式 控制 台 或 管理 后 台中 显示 对 

















象 调用 的 都 是 这 个 方法 。 这 个 方法 一 定 要 自 定义 ， 因 为 默认 的 实现 没什么 用 。 














。 get_absolute_url()。 这 个 方法 告诉 Django 如 何 计算 一 个 对 象 的 URL。Django 在 管理 后 台 和 需要 生成 




















对 象 的 URL 时 调用 这 个 方法 。 具 有 唯一 标识 的 URL 的 对 象 都 要 定义 这 个 方法 。 
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9.3.1 覆盖 预定 义 的 模型 方法 


还 有 一 系列 封装 数据 库 行为 的 模型 方法 有 时 也 需要 自 定义 。 尤 其 是 save() 和 delete()， 经 常 需要 修改 它们 的 
运作 方式 。 这 些 方法 〈 以 及 任何 其 他 模型 方法 ) 允许 覆盖 ， 让 你 调整 它们 的 行为 。 覆 盖 内 置 方法 的 一 个 典型 
使 用 场景 是 在 保存 对 象 时 做 些 事情 。 例 如 (save() 方法 接受 的 参数 参见 文档 ) : 





from django.db import models 


class Blog(models.Model): 
name = models.CharField(max_length=100) 
tagline = models.TextField() 


def save(self, *args, **kwargs): 
do_something() 
super(Blog，self).save(*args，**kwargs) # 调用 “真正 的 ”save () 方法 
do_something_else() 


也 可 以 在 特定 的 条 件 下 禁止 保存 : 





from django.db import models 


class Blog(models.Model): 
name = models.CharField(max_length=100) 
tagline = models.TextField() 


def save(self, *args, **kwargs): 
if self.name == "Yoko Ono's blog": 
return # Yoko 肯定 不 会 开 博客 的 ! 
else: 
super(Blog，self).save(*args，**kwargs) # 调用 “真正 的 ”save () 方法 


一 定 要 记得 调用 超 类 中 的 方法 ， 即 super(Blog，self).save(*args，**kwargs)， 确 保 把 对 象 保存 到 数据 库 
中 。 如 果 忘 记 ， 默 认 的 行为 不 会 发 生 ， 根 本 不 会 触及 数据 库 。 


此 外 ， 还 要 记得 传递 传 给 模型 方法 的 参数 ， 即 *args，**kwargs。Django 时 常 扩展 内 置 模型 方法 的 能 力 ， 为 
其 添加 新 参数 。 在 方法 定义 中 使 用 *args，**kwargs 能 确保 代码 自动 支持 未 来 添加 的 参数 。 





9.4 执行 原始 SQL 


模型 的 查询 API 不 够 用 时 ， 可 以 编写 原始 SQL。Django 为 执行 原始 SQL 查询 提供 了 两 种 方式 : 使 用 Manag- 
er.raw() 执行 ,返回 模型 实例 集合 ， 或 者 完全 不 用 模型 层 ， 直 接 执行 自 定义 的 SQL。 


编写 原始 SQL 时 要 非常 小 心 。 一 定 要 正确 转 义 通过 params 传人 的 参数 ， 以 防 SQL 注入 攻击 。 





9.5 执行 原始 查询 


管理 器 的 raw() 方法 用 于 执行 原始 的 SQL 查询 ， 其 返回 结果 是 模型 实例 集合 : 





Manager .raw(raw_query, params=None, translations=None) 
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这 个 方法 的 参数 是 一 个 原始 的 SQL 查询 ， 执 行 后 返回 一 个 django.db.modeLs.query.RawQuerySet 实例 。Raw- 
QuerySet 实例 可 以 像 常 规 的 QuerySet 对 象 一 样 迭 代 ， 获 取 里 面 的 模型 对 象 。 下 面 通 过 一 个 示例 说 明 。 假 设 有 
下 述 模型 ; 




















class Person(models.Model): 
first_name = models.CharField(...) 
Last_name = models.CharField(...) 
birth_date = modeLs.DateFieLd(...) 


可 以 像 这 样 执行 SQL 查询 : 


>>> for p in Person.objects.raw('SELECT * FROM myapp_person ' ) : 


print(p) 
John Smith 
Jane Jones 


当然 ， 这 个 示例 没什么 让 人 兴奋 的 ， 与 Person.objects.all() 的 效果 一 样 。 然 而 ，raw() 有 些 特别 强大 的 功 
能 


o 


9.5.1 模型 对 应 的 表 名 


上 例 中 的 Person 表 名 是 怎么 来 的 呢 ? Django 默认 把 “应 用 标注 ”(manage.py startapp 命令 指定 的 名 称 ) 与 类 
名 使 用 下 划 线 联结 在 一 起 得 到 数据 库 表 名 。 在 上 述 示例 中 ， 我 们 假设 Person 模型 在 myapp 应 用 中 ， 因 此 对 应 
的 表 是 myapp_person。 


更 多 信息 参见 db_table 选项 的 文档 ， 通 过 它 还 可 以 自 定义 数据 表 的 名 称 。 


Django 不 检查 传 给 raw() 方法 的 SQL 语句 ， 而 是 预期 查询 能 返回 一 系列 数据 库 行 ， 但 不 做 任 
何 强制 措施 。 如 果 不 返 回 一 系列 行 ， 抛 出 错误 〈 可 能 临 涩 难 懂 ) 。 























9.5.2 把 查询 中 的 字段 映射 到 模型 字段 上 


raw() 自动 把 查询 中 的 字段 映射 到 模型 字段 上 。 查 询 中 的 字段 顺序 无 关 紧要 。 也 就 是 说 ， 下 述 两 个 查询 的 作 


>>> Person.objects.raw('SELECT id, first_name, last_name, birth_date FROM myapp_person ' ) 


>>> Person.objects.raw('SELECT last_name, birth_date, first_name, id FROM myapp_person ' ) 





二 者 之 间 通 过 名 称 匹 配 。 这 意味 着 ， 可 以 使 用 SQL 的 As 子 句 把 查询 中 的 字段 映射 到 模型 字段 上 。 因 此 ， 如 
果 其 他 表 中 有 Person 数据 ， 可 以 轻易 将 其 映射 为 Person 实例: 


>>> Person.objects.raw('''SELECT first AS first_name, 
last AS last_name, 
bd As birth_date, 
pk AS id, 
FROM some_other_table''') 


只 要 名 称 匹配 就 能 正确 创建 模型 实例 。 此 外 ， 还 可 以 使 用 raw() 方法 的 translations 参数 把 查询 中 的 字段 映 
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射 到 模型 字段 上 。 这 个 参数 的 值 是 一 个 字典 ， 把 查询 中 的 字段 名 称 映射 到 模型 字段 的 名 称 上 。 例 如 ， 上 述 查 
询 还 可 以 写成 : 





>>> name_map = {'first': 'first _ name', 'last': 'last name', 'bd': 'birth date', 'pk': 'id'} 
>>> Person.objects.raw('SELECT * FROM some_other_table', translations=name_map) 


9.5.3 索引 查找 


raw() 支持 索引 ， 因 此 如 果 只 想 获得 第 一 个 结果 ， 可 以 这 样 写 : 








>>> first_person = Person.objects.raw('SELECT * FROM myapp_person')[0] 





然而 ， 索引 和 切片 不 是 在 数据 库 层 执行 的 。 如 果 数 据 库 中 的 Person 对 象 很 多 ， 最 好 在 SQL 查询 中 限制 数 


三 


星 : 


>>> first_person = Person.objects.raw('SELECT * FROM myapp_person LIMIT 1')[9] 


9.5.4 延期 模型 字段 
还 可 以 把 字段 排除 在 外 : 
>>> people = Person.objects.raw('SELECT id，first_name FROM myapp_person') 
这 个 查询 返回 的 是 延期 的 Person 对 象 (参阅 defer()) 。 这 意味 着 ， 查 询 排除 的 字段 将 按 需 加 载 。 例 如 : 


>>> for p in Person.objects.raw('SELECT id, first_name FROM myapp_person ' ) : 
print(p.first_name, # 这 个 属性 由 查询 取 回 
p.Last_name) # 这 个 属性 按 需 取 回 


John Smith 
Jane Jones 











从 表面 看 ， 好 像 这 个 查询 把 名 字 和 姓 都 取 回 了 。 然 而 ， 这 个 示例 其 实 发 起 了 三 个 查询 。raw() 执行 的 查询 只 
取 回 名 字 ， 两 人 的 姓 在 打印 时 按 需 取 回 。 


只 有 一 个 字段 是 不 能 排除 的 一 一 主键 字段 。Django 使 用 主键 标识 模型 实例 ， 因 此 必须 始终 包含 在 原始 查询 
中 。 忘 记 主 键 时 ， 抛 出 InvalidQuery 异常 。 





























9.5.5 添加 注解 


执行 的 查询 还 可 以 包含 模型 中 没有 定义 的 字段 。 例 如 ， 可 以 使 用 PostgreSQL 的 age() 函数 让 数据 库 计 算 所 得 
诸 人 的 年 龄 : 





>>> people = Person.objects.raw('SELECT *, age(birth_date) AS age FROM myapp_person') 
>>> for p in people: 
print("%s is %s." % (p.first_name, p.age)) 
John is 37. 
Jane is 42. 


9.5.6 为 raw( ) 传递 参数 


如 果 想 执行 参数 化 查询 ， 可 以 把 params 参数 传 给 raw(): 
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>>> lname = 'Doe' 
>>> Person.objects.raw('SELECT * FROM myapp_person WHERE Last_name = %s', [lname]) 

















params 的 值 是 一 个 参数 列表 或 字典 。 使 用 列表 时 ， 查 询 字 符 串 中 的 占 位 符 是 %s; 使 用 字典 时 ， 占 位 符 是 
%(key)s (当然 ， 其 中 的 key 要 替换 成 字典 的 键 ) 一 一 不 管 使 用 何 种 数据 库 引 警 ， 都 是 如 此 。 这 些 占 位 符 会 奉 
换 成 params 参数 中 的 值 。 


原始 查询 中 不 要 使 用 字符 串 格式 化 ! 


上 述 查 询 可 能 会 错误 地 写成 : 











>>> query = 'SELECT * FROM myapp_person WHERE Last_name = %s' % lname 
Person.objects.raw(query) 


千 万 别 这 么 写 ! 


使 用 params 参数 能 完全 避免 SQL 注入 攻击 。 这 是 一 种 常见 的 漏洞 ， 攻 击 者 能 设法 向 数据 库 中 
注入 任意 的 SQL。 如果 使 用 字符 串 插值 ， 迟 早 有 一 天 你 会 变 成 SQL 注入 的 牺牲 者 。 记 住 ， 一 
定 要 使 用 params 参数 ， 这 样 便 能 得 到 保护 。 











9.6 直接 执行 自 定 义 的 SQL 


有 时 ， 连 Manager.raw() 可 能 都 不 够 用 ， 例 如 执行 的 查询 不 完全 映射 到 模型 上 ， 或 者 直接 执行 UPDATE、IN- 
SERT 或 DELETE 查询 。 此 时 ， 完 全 可 以 直接 访问 数据 库 ， 绕 开 模型 层 。django.db.connection 对 象 表示 默认 的 
数据 库 连 接 。 若 想 使 用 这 个 数据 库 连接 ， 调 用 connection.cursor()， 获 取 一 个 游标 对 象 。 然 后 ， 调 用 cur- 
sor .execute(sql，[params]) 执行 SQL， 再 调用 cursor .fetchone() 或 cursor.fetchall() 返回 所 得 的 行 。 例 
如 : 


























from django.db import connection 


def my_custom sql(self): 
cursor = connection.cursor() 
CUrsor .execute("UPDATE bar SET foo = 1 WHERE baz = %s", [self.baz]) 
cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz]) 
row = cursor.fetchone() 


return row 








注意 ， 传 人 参数 时 ， 如 果 查 询 中 有 百 分 号 ， 应 该 编写 两 个 百 分 号 : 














CUrsor .execute("SELECT foo FROM bar WHERE baz = '30%'") 
CUrsor .execute("SELECT foo FROM bar WHERE baz = '30%%' AND 
id = %s", [self.id]) 


使 用 多 个 数据 库 时 ， 可 以 使 用 django.db.connections 获取 指定 数据 库 的 连接 (和 游标 ) 。django.db.connec- 
tions 是 一 个 类 似 字 典 的 对 象 ， 可 以 使 用 别名 取 回 指定 连接 : 




















from django.db import connections 
cursor = connections['my_db alias'].cursor() 


# 其 他 代码 ... 
默认 情况 下 ，Python DB API 返回 的 结果 不 带 字段 名 称 ， 因 此 得 到 的 是 列表 ， 而 不 是 字典 。 在 损失 少许 性 能 




















9.6 直接 执行 自 定义 的 SQL - 145 


的 前 提 下 ， 可 以 像 这 样 返回 字典 : 


def dictfetchall(cursor): 
# 把 游标 中 的 行 以 字典 的 形式 返回 
desc = cursor.description 
return [ 
dict(zip([col[0] for col in desc], row)) 
for row in cursor.fetchall() 


] 
二 者 之 间 的 区 别 如 下 例 所 示 : 





>>> cursor.execute("SELECT id, parent_id FROM test LIMIT 2"); 
>>> cursor.fetchall() 
((54360982L, None), (54360880L, None)) 


>>> CUrsor .execute("SELECT id, parent_id FROM test LIMIT 2"); 


>>> dictfetchall(cursor) 
[{'parent_id': None, 'id': 54360982L}, {'parent id': None, 'id': 54360880L}] 


9.6.1 连接 和 游标 





connection 和 cursor 基本 上 实现 了 PEP 249 定义 的 Python DB API， 不 过 对 事务 的 处 理 方式 有 所 不 同 。 如 果 
你 不 熟悉 Python DB API， 要 注意 ，cursor.execute() 中 的 SQL 语句 使 用 占 位 符 %s， 而 不 直接 把 参数 添加 到 
SQL 查询 中 。 




















使 用 占 位 符 时 ， 底 层 数 据 库 库 会 自动 转 义 参数 。 还 要 注意 ，Django 使 用 的 占 位 符 是 %s ， 而 不 是 ?。 后 者 是 
SQLite 的 Python 绑 定 使 用 的 。 这 样 做 是 为 了 一 致 性 和 健全 性 。 像 下 面 这 样 把 游标 当做 上 下 文 管理 器 使 用 : 























with connection.cursor() as c: 
c.execute(...) 


等 效 于 : 
Cc = connection.cursor() 
trys 
c.execute(...) 
finally: 
c.close() 


9.6.2 添加 额外 的 管理 器 方法 


























添加 额外 的 管理 器 方法 是 为 模型 添加 数据 表层 功能 的 首选 方式 。 (数据 行 层 的 功能 ， 即 在 模型 对 象 的 单个 实 
例 上 执行 的 操作 ， 使 用 模型 方法 。) 自 定义 的 管理 器 方法 可 以 返回 任何 需要 的 内 容 ， 不 一 定 是 QuerySet。 





























例如 ， 下 面 这 个 自 定 义 的 管理 器 提供 了 with_counts() 方法 ， 它 返回 所 有 0pinionPoll 对 象 ， 每 个 对 象 都 有 和 额 
外 的 num_responses 属性 ， 其 值 为 聚合 查询 的 结果 : 

















from django.db import models 


class PoLLManager(modeLs.Manager ) : 
def with_counts(seLf) : 
from django.db import connection 
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cursor = connection.cursor() 

cursor .execute(""" 
SELECT p.id, p.question, p.poll_date, COUNT(*) 
FROM polls_opinionpoll p, polls_ response r 
WHERE pid = rpolt id 
GROUP BY p.id, p.question, p.poll_ date 
ORDER BY p.poll_date DESC""") 

result list = [] 

for row in cursor.fetchall(): 
p = self.model(id=row[0], question=row[1], poll_date=row[2]) 
p.num_responses = row[3] 
result_list.append(p) 

return result_list 


class OpinionPoll(models.Model): 
question = models.CharField(max_length=200) 
poll_date = models.DateField() 
objects = PollManager() 


class Response(models.Model): 
poll = models.ForeignKey(Opinionpoll) 
person_name = models.CharField(max_length=50) 
response = models.TextField() 





对 这 个 示例 来 说 ， 要 使 用 0pinionPoll.objects.with_counts() 获取 具有 num_responses 属性 的 OpinionPoll 对 
象 列表 。 还 有 一 点 要 注意 : 管理 器 方法 可 以 访问 seLf.modeL， 获 取 所 依附 的 模型 类 。 


9.7 接 下 来 























下 一 章 说 明 Django 的 通用 视图 框架 。 遵 守 常 见 模式 构建 网 站 时 ， 使 用 通用 视图 可 以 节省 时 间 。 
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本 书 不 断 强调 ， 往 坏 了 说 ，Web 开发 是 单调 乏味 的 。 目 前 ， 我 们 介绍 了 Django 为 了 缓和 这 种 单调 在 模型 和 
模板 层 上 所 做 的 努力 ， 但 是 Web 开发 者 在 视图 层 也 会 经 历 这 种 乏味 的 体验 。 








为 了 降低 这 方面 的 痛苦 ，Django 开发 了 通用 视图 (generic view) 。 























通用 视图 把 视图 开发 中 常用 的 写法 和 模式 抽象 出 来 ， 让 你 编写 少量 代码 就 能 快速 实现 常见 的 数据 视图 。 显 示 
对 象 列表 就 是 这 样 一 种 任务 。 


了 通用 视图 ， 可 以 把 模型 作为 额外 的 参数 传 给 URL 配置 。Django 自 带 的 通用 视图 能 实现 下 述 功能 : 




































































。 列 出 对 象 并 显示 单个 对 象 的 详细 信息 。 如 果 创 建 一 个 管理 会 议 的 应 用 程序 ， 那 么 TalkListView 和 Reg- 
isteredUserListView 就 是 列表 视图 。 某 一 个 演讲 的 页 面 就 是 详细 信息 视图 。 


。 呈现 基于 日 期 的 对 象 ， 显 示 为 年 月 日 归档 页 面 〈 带 有 详细 信息 ) ， 以 及 “最 新 "页面 。 
。 让 用 户 创 建 、 更 新 和 删除 对 象 一 一 需 不 需要 授权 都 行 。 
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综 上 ， 这 些 视图 提供 了 简单 易 用 的 接口 ， 在 视图 中 显示 数据 库 里 的 数据 时 能 为 开发 者 执行 多 数 常见 的 任务 。 
然而 ， 显 示 视 图 只 是 Django 全 面 的 基于 类 的 视图 系统 的 作用 之 一 。Django 提供 的 其 他 基于 类 的 视图 的 完整 
介绍 和 详细 说 明 参 见 附 录 C。 












































10.1 对 和 象 的 通用 视图 





在 视图 中 呈现 数据 库 里 的 内 容 时 最 能 体现 Django 的 通用 视图 是 多 么 强大 。 这 是 一 件 十 分 常见 的 任务 ， 因 此 
Django 内 建 了 很 多 这 方面 的 通用 视图 ， 不 费 吹 灰 之 力 就 能 生成 对 象 列表 和 详细 信息 视图 。 














下 面 举 几 个 例子 。 我 们 将 使 用 下 述 模型 ; 


# models.py 
from django.db import models 


class Publisher(models.Model): 
name = models.CharField(max_length=30) 
address = models.CharField(max_length=50) 
city = models.CharField(max_length=60) 
state_province = models.CharField(max_length=30) 
country = models.CharField(max_length=50) 
website = models.URLField() 


class Meta: 
ordering = ["-name"] 


def _str_(self): 
return self.name 


class Author(models.Model): 
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salutation = models.CharField(max_length=10) 

name = models.CharField(max_length=200) 

email = models.EmailField() 

headshot = models.ImageField(upload_ to='author_headshots') 


def _str__(self): 
return self.name 


class Book(models.Model): 
title = models.CharField(max_length=100) 
authors = models.ManyToManyField('Author') 
publisher = models.ForeignKey(Publisher) 
publication date = models.DateField() 





然后 ， 定 义 一 个 视图 : 











# views.py 
from django.views.generic import ListView 
from books.models import Publisher 


class PublisherList(ListView): 
model = Publisher 


最 后 ， 把 视图 与 URL 关联 起 来 : 


# urls.py 
from django.conf.urls import url 
from books.views import PublisherList 


urlpatterns = [ 
url(r'^publishers/$', PublisherList.as_view()), 
] 








这 就 是 我 们 需要 编写 的 全 部 Python 代码。 当然， 还 要 编写 模板 。 我 们 可 以 为 视图 添加 一 个 template_name 属 
性 ， 明 确 指 明 使 用 哪个 模板 ， 如 果 没 明确 指定 ，Django 将 从 对 象 的 名 称 中 推 知 。 这 里 ， 推 知 的 模板 是 books/ 
pubLisher_List.htmL， 其 中 “books”" 是 模型 所 在 应 用 的 名 称 ,“publisher" 是 模型 名 的 小 写 形式 。 




















因此 ， 如 果 TEMPLATES 设置 中 DjangoTemplates 后 台 的 APP_DIRS 选项 设 为 True， 那么 这 个 模板 的 位 置 是 
/path/to/project/books/templates/books/publisher_list.html, 








演 染 这 个 模板 时 ， 上 下 文中 有 个 名 为 object_List 的 变量 ， 它 的 值 是 所 有 出 版 社 对 象 。 下 面 是 一 个 十 分 简单 
的 模板 : 


{% extends "base.html" %} 


{% block content %} 
<h2>Publishers</h2> 
<ul> 
{% for publisher in object_ list %} 
<li>{{ publisher.name }}</li> 
{% endfor %} 
</UuLls 
{% endblock %} 
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等 


以 上 就 是 全 部 代码 。 通 用 视图 所 有 的 强大 功能 都 通过 修改 属性 实现 。 附 录 C 将 详细 说 明 所 有 通用 视图 及 其 
项 ， 还 将 介绍 定制 和 扩展 通用 视图 的 一 些 常 见方 式 。 









































10.2 提供 “友好 的 "模板 上 下 文 


你 可 能 注意 到 了 ， 上 述 出 版 社 列 表 模 板 示例 把 所 有 出 版 社 存储 在 一 个 名 为 object_list 的 变量 中 。 这 样 虽 然 
可 行 ， 但 是 对 模板 编写 人 不 够 友好 ， 他 们 想 知道 的 是 处 理 的 是 出 版 社 。 


如 果 处 理 的 是 模型 对 象 ，Django 已 经 为 你 提供 了 这 样 一 个 变量 。 处 理 对 象 或 查询 集合 时 ，Django 将 向 上 下 文 
中 添加 一 个 以 模型 类 名 小 写 形式 命名 的 变量 。 这 个 变量 与 object_List 同时 存在 ， 不 过 所 含 的 数据 完全 相 
同 。 这 里 ， 变 量 名 为 publisher_list。 









































如 果 这 还 不 够 ， 可 以 自行 设 定 上 下 文 变量 的 名 称 。 通 用 视图 的 context_object_name 属性 用 于 指定 要 使 用 的 上 
下 文 变量 名 : 





























# ViLews .py 
from django.views.generic import ListView 
from books.models import Publisher 


class PublisherList(ListView): 


model = Publisher 
Context_object_name = 'my_favorite_publishers' 


为 context_object_name 设 定 一 个 友好 的 值 总 是 好 的 ， 设 计 模 板 的 同事 会 感谢 你 的 。 


10.3 提供 额外 的 上 下 文 变量 




















通常 ， 除 了 通用 视图 提供 的 信息 之 外 ， 还 想 显 示 一 些 额 外 信息 。 例 如 ， 在 各 个 出 版 社 的 详细 信息 页 面 显示 出 
版 的 图 书 列表 。Detailview 通用 视图 在 上 下 文中 提供 了 出 版 社 信息 ， 但 是 如 何在 模板 中 获取 额外 的 信息 呢 ? 









































答案 是 扩展 DetailView， 自 己 实现 get_context_data 方法 。 默 认 的 实现 只 为 模板 提供 该 显示 的 对 象 ， 不 过 可 
以 覆盖 ， 提 供 更 多 信息 : 


from django.views.generic import DetailView 
from books.models import Publisher, Book 


class PublisherDetail(DetailView): 
model = Publisher 


def get context data(self, **kwargs): 
# 先 调用 原来 的 实现 ， 获 取 上 下 文 
context = super(PublisherDetail, self).get context_data(**kwargs) 
# 把 所 有 图 书 构成 的 查询 集合 添加 到 上 下 文中 
Context[ 'book_List'] = Book.objects.all() 
return context 
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默认 情况 下 ，get_context_data 会 把 所 有 父 类 的 上 下 文 数据 与 当前 类 的 合并 在 一 起 。 如 果 在 调 
整 上 下 文 的 子 类 中 不 想 使 用 这 种 行为 ， 要 在 超 类 上 调用 get_context_data。 如 果 两 个 类 没有 在 
上 下 文中 定义 相同 的 键 ， 这 样 得 到 的 结果 符合 预期 。 但 是 ， 如 果 尝 试 尾 盖 超 类 设 定 的 键 (在 调 
用 super 之 后 ) ， 当 子 类 想 覆 盖 所 有 超 类 时 ， 子 类 也 必须 在 调用 super 之 后 显 式 设 定 那个 键 。 











10.4 显示 对 和 象 子 集 


现在 仔细 分 析 一 下 我 们 一 直 使 用 的 model 属性 。 这 个 属性 指定 视图 操作 的 数据 库 模型 ， 在 操作 单个 对 象 或 对 
象 集合 的 通用 视图 中 都 可 用 。 然 而 ， 这 不 是 指定 视图 操作 哪些 对 象 的 唯一 方式 ， 此 外 还 可 以 使 用 queryset 属 
性 指定 一 组 对 象 ; 








from django.views.generic import DetailView 
from books.models import Publisher 


class PublisherDetail(DetailView): 
Context_object_name = 'publisher' 
queryset = Publisher.objects.all() 


model = Publisher 其 实 是 queryset = Publisher .objects.all() 的 简洁 形式 。 然 而 ， 使 用 queryset 可 以 过 滤 
对 象 列 表 ， 进 一 步 指 定 要 在 视图 中 查看 的 对 象 。 下 面 举 个 列子 。 我 们 可 能 想 按 照 出 版 日 期 排序 图 书 列表 ， 把 
最 近 出 版 的 放 在 前 面 : 








from django.views.generic import ListView 
from books.models import Book 


class BookList(ListView): 
queryset = Book.objects.order_by('-publication date') 
context_object_name = 'book_list' 


这 个 示例 相当 简单 ， 不 过 却 很 好 地 说 明了 其 中 的 思想 。 当 然 ， 通常 你 想 做 的 可 能 不 仅仅 是 重新 排序 对 象 。 如 
果 想 星 现 特定 出 版 社 出 版 的 图 书 列表 ， 也 可 以 使 用 这 个 技术 : 





from django.views.generic import ListView 
from books.models import Book 


class AcmeBookList(ListView): 


context_object name = 'book_list' 
queryset = Book.objects.filter(publisher__name='Acme Publishing') 
tempLate_name = 'books/acme_list.html’ 


注意 ， 除 了 过 滤 查 询 集合 之 外 ， 我 们 还 自 定义 了 模板 名 称 。 如 若 不 然 ， 通 用 视图 会 使 用 显示 普通 对 象 列表 的 
模板 ， 而 这 可 能 不 是 你 想 要 的 。 


还 应 注意 ， 这 不 是 显示 特定 出 版 社 旗下 图 书 的 优雅 方式 。 如 果 想 添加 关于 出 版 社 的 其 他 页 面 ， 需 要 在 URL 配 
置 中 多 添加 几 行 代码 ， 而 当 出 版 社 变 多 后 ， 这 样 做 也 不 合理 。 下 一 节 将 解决 这 个 问题 。 
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10.5 动态 过 滤 














另 一 个 常见 的 需求 是 根据 URL 中 指定 的 键 过 滤 列 表 页 面 中 的 对 象 。 前 面 ， 我 们 在 URL 配置 中 硬 编码 出 版 社 
的 名 称 ， 但 是 如 果 我 们 想 编 写 一 个 视图 显示 随意 一 家 出 版 社 旗下 的 所 有 图 书 呢 ? 


这 也 很 方便 ， 我 们 可 以 覆盖 ListView 的 get_queryset() 方法 。 它 的 默认 实现 是 返回 queryset 属性 的 值 ， 不 
过 我 们 可 以 添加 更 多 逻辑 。 这 里 的 关键 是 ， 调 用 基于 类 的 视图 时 ， 很 多 有 用 的 东西 存储 到 self 中 了 ， 除 了 请 
求 (self.request) 之 外 ， 还 有 根据 URL 配置 捕获 的 位 置 参 数 (self.args) 和 关键 字 参 数 

(self.kwargs) 。 






















































































下 述 URL 配置 只 有 一 个 捕获 组 : 











# urls.py 
from django.conf.urls import url 
from books.views import PublisherBookList 


urlpatterns = [ 
url(r'^books/([\w-]+)/$', PublisherBookList.as_view()), 
] 


然后 ， 编 写 PublisherBookList 视图 类 : 


# views.py 

from django.shortcuts import get object_or_404 
from django.views.generic import ListView 

from books.models import Book, Publisher 


class PublisherBookList(ListView): 
tempLate_name = 'books/books_by_publisher.html' 
def get queryset(self): 


self.publisher = get object or_404(Publisher, name=self.args[0]) 
return Book.objects.filter(publisher=self.publisher) 





可 以 看 出 ， 为 查询 集合 添加 逻辑 还 是 相当 容易 的 。 如 果 需 要 ， 可 以 使 用 seLf.request.user 通过 当前 用 户 过 
滤 ， 或 者 实现 其 他 更 复杂 的 逻辑 。 与 此 同时 ， 我 们 还 可 以 把 出 版 社 对 象 添加 到 上 下 文中 ， 供 模板 使 用 : 





着 


def get context data(self, **kwargs): 
# 先 调用 原来 的 实现 ， 获 取 上 下 文 
context = super(PublisherBookList, self).get context_data(**kwargs) 


# 添加 出 版 社 对 象 
Context[ 'pubLisher '] = self.publisher 
return context 检 执行 额外 的 操作 





下 面 再 介绍 一 个 常见 的 需求 : 在 调用 通用 视图 前 后 做 些 额外 工作 。 假 设 Author 模型 中 有 个 Last_accessed 字 
段 ， 用 于 记录 这 位 作者 的 信息 被 人 查看 的 最 后 时 间 : 











# models.py 
from django.db import models 
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class Author(modeLs .ModetL) : 


salutation 


= models.CharField(max_length=10) 


name = models.CharField(max_length=200) 
email = models.EmailField() 


headshot = 


models.ImageField(upload_ to='author_headshots') 


Last_accessed = models.DateTimeField() 








当然 ，Detailview 类 对 这 个 字段 一 无 所 知 ， 不 过 我 们 依然 可 以 轻易 自 定 义 视图 ， 及 时 更 新 这 个 字段 。 首 先 ， 


我 们 要 在 URL 配置 中 添加 author-detail， 指 向 一 个 自 定义 的 视图 : 






































from django.conf.urls import url 


from books.views import AuthorDetailView 


urlpatterns = [ 


#... 


url(r'^authors/(?P<pk>[0-9]+)/$', AuthorDetailView.as_view(), 
name='author -detail'), 


] 





然后 要 编写 那个 视图 














。get_object 是 用 于 检索 对 象 的 方法 ， 因 此 我 们 只 需 覆 盖 它 ， 执 行 相关 的 调用 : 


from django.views.generic import DetailView 


from django.utils import timezone 


from books.models import Author 


class AuthorDetailView(DetailView): 


queryset = Author .objects.all() 


def get object(self): 
# 调用 超 类 中 的 同名 方法 


object 


= super(AuthorDetailView, self).get _ object() 


# 记录 最 后 访问 日 期 
object.Last_accessed = timezone.now() 


object.save() 
# 返回 对 象 
return object 














这 里 ，URL 配置 使 








的 分 组 名 为 pk， 这 是 DetailView 过 滤 查 询 集 合 时 查找 主键 所 用 的 默认 名 称 。 








如 果 把 这 个 分 组 命名 为 其 他 值 ， 要 在 视图 中 设 定 pk_urL_kwarg。 详 情 参 见 DetaitLVview 的 文档 。 


10.6 接 下 来 


本 章 只 涵盖 了 Django 自 带 的 部 分 通用 视图 ， 不 过 基本 思想 几乎 适用 于 所 有 通用 视图 。 附 录 C 将 详细 说 明 全 




















t 





部 可 用 的 通用 视图 ， 如 果 想 充分 利用 通用 视图 的 强大 功能 ， 建 议 你 阅读 。 








本 书 对 模型 、 模 板 和 视图 的 高 级 用 法 的 讨论 至 此 结束 。 接 下 来 的 几 章 涵盖 现代 商业 网 站 中 十 分 常见 的 几 个 功 


能 。 首 先 ， 我 们 将 探讨 构建 交互 式 网 站 的 一 个 基本 话题 一 一 用 户 管理 。 
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现代 的 交互 式 网 站 有 相当 一 部 分 比例 有 某 种 形式 的 用 户 交 互 ， 简 单 的 交互 有 在 博客 中 发 表 评 论 ， 全 面 的 交互 





















































新 闻 网 站 中 编辑 对 文章 的 控制 。 如 果 网 站 以 某 种 形式 提供 电 商 服务 ， 验 证 付费 顾客 的 身份 并 核准 权限 是 基 
本 需求 。 









































就 算 只 是 管理 用 户 〈 忘 记 用 户 名 、 密 码 ， 保 持 用 户 信息 最 新 ) 也 是 一 件 痛苦 的 事 。 对 程序 员 来 说 ， 编 写 一 个 





身份 验证 系统 更 是 难 上 加 难 。 

































































幸运 的 是 ，Django 自 带 了 一 套 系统 ， 能 管理 用 户 的 账户 、 分 组 和 权限 ， 并 且 实 现 了 基于 cookie 的 用 户 会 话 。 























与 Django 的 多 数 内 置 功能 一 样 ， 这 套 系 统 的 默认 实现 也 完全 可 以 扩展 和 定制 ， 以 满足 具体 项 目的 需求 。 下 面 


就 


十 














探索 这 个 系统 。 


11.1 概览 


Django 的 身份 验证 系统 既 能 验证 身份 ， 也 能 核准 权限 。 简 单 来 说 ， 身 份 验 证 是 指 确认 用 户 是 不 是 他 声称 的 那 


















































个 人 ， 而 权限 核准 是 指 确定 通过 身份 验证 的 用 户 能 做 什么 。 这 里 ， 我 们 使 用 “身份 验证 ” 指 代 这 两 个 任务 。 
Django 的 身份 验证 系统 包括 : 

















用 户 

权限 : 二 元 (是 或 否 ) 旗 标 ， 指 明 用 户 是 否 能 执行 特定 的 任务 
分 组 : 把 标注 和 权限 赋予 多 个 用 户 的 通用 方式 

可 配置 的 密码 哈 希 系统 
管理 身份 验证 和 权限 核准 的 表单 
登录 用 户 或 限制 内 容 的 视图 工具 
可 更 换 的 后 端 系统 




















































































































Django 的 身份 验证 系统 十 分 通用 ， 没 有 提供 Web 身份 验证 系统 中 某 些 常用 的 功能 。 某 些 常用 功能 通过 第 三 
方 包 实现 : 


密码 强度 检查 
登录 尝试 次 数 限制 
通过 第 三 方 验证 身份 (如 OAuth) 





11.2 使 用 Django 的 身份 验证 系统 





Django 的 身份 验证 系统 默认 实现 了 多 数 常见 的 需求 ， 能 处 理 相当 多 的 任务 ， 而 且 小 心 实现 了 密码 和 权限 。 如 
你 的 项 目 不 想 使 用 默认 的 实现 ，Django 也 允许 对 身份 验证 系统 做 深入 地 扩展 和 定制 。 


四 
个 
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11.3 User 对 象 

















User 对 象 是 这 个 身份 验证 系统 的 核心 ， 通 常用 于 标识 与 网 站 交互 的 人 ， 还 用 于 限制 访问 、 记 录用 户 资料 ， 以 
及 把 内 容 与 创建 人 关联 起 来 ， 等 等 。 在 Django 的 身份 验证 框架 中 ， 只 有 一 个 用 户 类 存在 ， 因 此 superusers 

或 管理 后 台 的 staff 用 户 只 是 设 定 了 特殊 属性 的 用 户 对 象 ， 而 不 是 分 属 不 同类 的 用 户 对 象 。 默 认 用 户主 要 有 
下 面 几 个 属性 : 





















































。 USsername 
。 password 

。 email 

。 first_name 


。 Last_name 


11.3.1 创建 超级 用 户 


超级 用 户 使 用 createsuperuser 命令 创建 : 


python manage.py createsuperuser --Username=joe --email=joe@Qexample.com 














上 述 命令 会 提示 你 输入 密码 。 输 入 密码 后 ， 立 即 创建 指定 的 超级 用 户 。 如 果 没有 指定 --usernane 或 -ematl 
选项 ， 会 提示 你 输入 这 两 个 值 。 











11.3.2 创建 用 户 

创建 和 管理 用 户 最 简单 、 最 不 易 出 错 的 方式 是 使 用 Django 管理 后 台 。Django 还 内 置 了 登录 、 退 出 和 修改 密 
码 的 视图 和 表单 。 本 章 后 面 会 说 明 如 何 通 过 管理 后 台 和 普通 的 表单 管理 用 户 ， 现 在 先 来 看 如 何 直 接 验 证 用 户 
的 身份 。 


创建 用 户 最 直接 的 方式 是 使 用 create_user() 辅助 孔 数 : 


























































































































>>> from django.contrib.auth.models import User 
>>> User = User.objects.create user('john', 'lennon@thebeatles.com', 'johnpassword') 


# 此 时 ，User 是 一 个 User 对 象 ， 而且 已 经 保存 到 数据 库 中 
# 如 果 想 修改 其 他 字段 的 值 ， 可 以 继续 修改 属性 

>>> USser.Last_name = 'Lennon' 

>>> User.save() 


11.3.3 修改 密码 


Django 不 在 用 户 模 型 中 存储 原始 (明文 ) 密码 ， 只 存储 密码 的 哈 希 值 。 因 此 ， 不 要 试图 直接 处 理 用户 的 密 
码 。 正 是 因为 这 样 ， 创 建 密码 才 要 使 用 一 个 辅助 函数 。 如 果 想 修改 用 户 的 密码 ， 有 两 个 选择 : 





















































1， 在 命令 行 中 使 用 manage.py changepassword username 命令 修改 用 户 的 密码 。 这 个 命令 会 提示 你 输入 两 
次 密码 。 如 果 两 次 输入 的 内 容 匹 配 ， 立 即 修改 密码 。 如 果 不 指定 用 户 名 ， 这 个 命令 会 尝试 修改 与 当前 
系统 用 户 的 用 户 名 一 致 的 那个 用 户 的 密码 。 

2， 还 可 以 通过 编程 方式 ， 使 用 set_password() 方法 修改 : 
































>>> from django.contrib.auth.models import User 
>>> Uy = User.objects.get(username= ' john ' ) 
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>>> U.Sset_password('new password') 
>>> U.save() 


如 果 启 用 了 SessionAuthenticationMiddleware， 修 改 用 户 的 密码 后 ， 那 个 用 户 的 所 有 会 话 都 会 退出 。 


11.4 权限 和 权限 核准 














Django 自 带 了 一 个 简单 的 权限 系统 。 通 过 它 可 以 为 指定 的 用 户 和 用 户 组 赋予 权限 。Django 管理 后 台 就 用 到 了 
这 个 系统 ， 当 然 也 欢迎 在 你 自己 的 代码 中 使 用 。Django 管理 后 台 使 用 权限 控制 下 述 操作 : 


























。 限制 有 某 种 对 象 的 “添加 ”权限 才能 查看 “添加 ”表单 和 添加 对 象 。 
。 限制 有 某 种 对 象 的 “修改 "权限 才能 查看 修改 列表 、“ 修 改 " 表 单 和 修改 对 象 。 
。 限制 有 某 种 对 象 的 “删除 ”权限 才能 删除 对 象 。 
































权限 不 仅 可 以 在 一 种 对 象 上 设 定 ， 也 可 以 在 具体 的 对 象 实例 上 设 定 。 使 用 ModelAdmin 类 提供 的 has_add_per- 
mission()、has_change_permission() 和 has_delete_permission() 方法 可 以 定制 同一 类 型 不 同 实例 的 权限 。 
User 对 象 有 两 个 多 对 多 字段 ， 分 别 是 groups 和 user_permissions。User 对 象 访问 相关 对 象 的 方式 与 其 他 
Django 模型 一 样 。 























11.4.1 默认 权限 


在 INSTALLED_APPS 设置 中 列 出 django.contrib.auth 后 ， 安 装 的 各 个 应 用 中 的 每 个 Django 模型 默认 都 有 三 个 
权限 : 添加 、 修 改 和 删除 。 每 次 运行 manage.py migrate 命令 创建 新 模型 时 都 会 为 其 赋予 这 三 个 权限 。 


11.4.2 分 组 





django.contrib.auth.models.Group 模型 是 为 用 户 分 类 的 通用 方式 ， 这 样 便 可 以 为 一 批 用 户 赋予 权限 或 添加 其 
他 标注 。 用 户 所 属 的 分 组 数量 不 限 。 一 个 分 组 中 的 用 户 自动 获得 赋予 那个 分 组 的 权限 。 例 如 “Site editors” 分 组 
Can_edit_home_page 权限 ， 那 么 其 中 的 任何 一 个 用 户 都 有 这 个 权限 。 


除了 权限 之 外 ， 分 组 还 是 为 用 户 分 类 的 便捷 方式 ， 分 组 后 可 以 给 用 户 添 加 标签 ， 或 者 扩展 功能 。 例 如 ， 可 以 
创建 “Special users” 分 组 ， 然 后 编写 代码 ， 人 允许 这 一 组 中 的 用 户 访问 只 有 会 员 才能 查看 的 内 容 ， 或 者 发 送 只 给 
会 员 看 的 电子 邮件 。 













































































11.4.3 通过 编程 方式 创建 权限 


除了 可 以 在 模型 的 Meta 类 中 定制 权限 之 外 ， 还 可 以 直接 创建 权限 。 例 如 ， 为 books 应 用 中 的 BookReview 模型 
赋予 can_publish 权限 : 




















from books.models import BookReview 
from django.contrib.auth.models import Group, Permission 
from django.contrib.contenttypes.models import ContentType 


content_type = ContentType.objects.get_for_model(BookReview) 

permission = Permission.objects.create(codename='can_publish', 
name='Can Publish Reviews ' ， 
content_type=content_type) 


然后 ， 可 以 通过 User 的 user_permissions 属性 把 这 个 权限 赋予 一 个 用 户 ， 或 者 通过 Group 的 permissions 属 
性 把 这 个 权限 赋予 一 个 分 组 。 
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11.4.4 权限 缓存 

















首次 检查 用 户 对 象 的 权限 时 ，ModelBackend 会 缓存 权限 。 这 在 “请 求 - 啊 应 ”循环 中 是 没 问 题 的 ， 因 为 添加 权限 
后 往往 不 会 立即 检查 〈 例 如 在 管理 后 台中 ) 。 





如 果 添 加 权限 后 需要 立即 检查 ， 例 如 在 测试 或 视图 中 ， 最 简单 的 解决 方法 是 


例如 : 








mm 


新 从 数据 库 中 获取 用 户 对 象 。 











from django.contrib.auth.models import Permission, User 
from django.shortcuts import get object or_404 


def user_gains_perms(request, user_id): 


User = get_ object or_404(User, pk=user_id) 
# 只 要 检查 了 权限 ， 就 会 把 当前 的 权限 缓存 起 来 
User .has_perm( 'books.change_bar ') 


permission = Permission.objects.get(codename='change_bar') 
User .user_permissions.add(permission) 


# 检查 的 是 缓存 的 权限 
User .has_perm( 'books.change_bar ') # False 


# 重新 请 求 User 实例 
user = get_object_or_404(User，pk=user_id) 


# 重新 缓存 权限 


user.has_perm('books.change_bar') # True 
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Django 使 用 会 话 和 中 间 件 把 身份 验证 系统 插入 request 对 象 ， 为 每 个 请 求 提供 request.user 属性 ， 表 示 当 前 
用 户 。 如 果 未 登陆 ， 这 个 属性 的 值 是 一 个 AnonymousUser 实例 ， 否 则 是 是 一 个 User 实例 。 这 两 种 情况 可 以 使 
用 is_authenticated() 方法 区 分 ,例如 : 











if request.user.is_authenticated(): 


# 处 理 通过 身份 验证 的 用 户 


else: 


# 处 理 匿 名 用 户 


11.5.1 如 何 登 录用 户 


在 视图 中 使 用 tlogin() 登录 用 户 。 它 的 参数 是 一 个 HttpRequest 对 象 和 一 个 User 对 象 。login() 使 用 Django 











的 会 话 框 架 把 用 户 的 ID 保存 到 会 话 中 。 注 意 ， 匿 名 期 间 设 定 的 会 话 数据 在 用 户 登录 后 依然 存在 。 下 述 示 例 
展示 authenticate() 和 Login() 的 用 法 : 











from django.contrib.auth import authenticate, login 


def my_view(request): 


Username = request.POST['username'] 
password = request.POST['password'] 
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user = authenticate(username=Username，password=password) 
if user is not None: 
if user.is active: 
login(request, user) 
# 重 定向 到 成 功 登 录 页 面 
else: 
# 返回 “账户 未 激活 ”错误 消息 
else: 
# 返回 “无 效 登 录 ” 错 误 消息 


先 调 用 authenticate() 


自己 动手 登录 用 户 时 ， 必 须 在 login() 之 前 调用 authenticate()。authenticate() 在 User 对 象 
上 设 定 一 个 属性 ， 指 明成 功 验 证 用 户 身份 的 是 哪个 身份 验证 后 端 ， 而 登录 过 程 中 需要 使 用 这 个 
言 息 。 如 果 直 接 登 录 从 数据 库 中 检索 的 用 户 对 象 ，Django 报错 。 





11.5.2 如 何 退 出 用 户 


在 视图 中 退出 通过 Login() 登录 的 用 户 使 用 Logout()。 这 个 函数 的 参数 是 一 个 HttpRequest 对 象 ， 而 且 没 有 
返回 值 。 例 如 : 


from django.contrib.auth import Logout 


def logout view(request): 
logout(request) 
# 重 定向 到 成 功 退 出 页 面 


注意 ， 如 果 用 户 未 登录 ，logout() 函数 不 报错 。 调 用 logout() 函数 后 ， 当 前 请 求 的 会 话 数据 完全 清除 ， 所 有 
数据 将 被 删除 。 这 样 能 避免 其 他 人 在 登录 的 Web 浏览 器 中 访问 用 户 之 前 的 会 话 数据 。 


如 果 想 让 会 话 中 的 数据 在 退出 后 依然 可 用 ， 调 用 Logout() 函数 之 后 再 把 数据 存 人 会 话 。 











11.5.3 限制 已 登录 用 户 的 访问 


直接 方式 


限制 访问 页 面 简单 直接 的 方式 是 检查 request.user .is_authenticated()， 如 果 未 通过 ， 可 以 重 定向 到 登录 页 
团 : 














from django.shortcuts import redirect 


def my_view(request): 
if not request.user.is authenticated(): 
return redirect('/login/?next=%s' % request.path) 
关 





from django.shortcuts import render 


def my_view(request): 
if not request.user.is authenticated(): 
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return render(request, 'books/Login_error .htmtL ' ) 


login_required 装饰 器 














若 想 再 简单 一 些 ， 可 以 使 用 便利 的 login_required() 装饰 髓 : 
from django.contrib.auth.decorators import login_required 


@login_required 


def my_view(request): 


login_required() 的 作用 如 下 : 


。 如 果 用 户 未 登录 ， 重 定向 到 LOGIN_URL， 并 把 当前 绝对 路 径 添加 到 查询 字符 串 中 。 例 如 : /accounts/ 


login/?next=/reviews/3/。 


。 如 果 用 户 已 登录 ， 正 常 执行 视图 。 视 图 代码 可 以 放心 假定 用 户 已 登录 。 





























默认 ， 成 功 通过 身份 验证 后 重 定向 的 目标 路 径 存 储 在 名 为 next 的 查询 字符 串 参 数 中 。 如 果 想 为 这 个 参数 提供 
其 他 名 称 ， 可 以 设 定 Login_required() 可 选 的 redirect_field_name 参数 . 





from django.contrib.auth.decorators import Login_requtred 


@login required(redirect field name='my_redirect field') 
def my_view(request): 








注意 ， 如 果 为 redirect_field_name 提供 了 值 ， 可 能 还 要 定制 登录 模板 ， 因 为 模板 上 下 文中 存储 重 定向 路 径 的 
变量 名 是 redirect_fieLd_name 的 值 ， 而 不 再 是 默认 的 next。login_required() 还 有 个 可 选 的 Login_urt 参 
数 。 例如 : 





from django.contrib.auth.decorators import login_required 


@login_required(login_url='/accounts/Llogin/') 
def my_view(request): 





注意 ， 如 果 不 指定 Login_url 参数 ， 要 确保 把 LOGIN_URL 设 为 正确 的 登录 视图 。 例 如 ， 使 用 默认 配置 时 ， 要 
把 下 述 代码 添加 到 URL 配置 中 : 








from django.contrib.auth import views as auth_views 


uUrLCr'^accounts/Login/S' ，auth_views.Login)， 


LOGIN_URL 的 值 还 可 以 是 视图 函数 名 称 或 具名 URL 模式 。 这 样 ， 无 需 修改 设置 就 可 以 在 URL 配置 中 自由 映 
射 登录 视图 。 





注意 


login_required 装饰 器 不 检查 用 户 的 is_active 旗 标 。 
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根据 测试 条 件 限 制 访 问 











如 果 想 根据 权限 或 其 他 测试 条 件 限 制 访问 ， 要 做 的 基本 上 与 前 一 节 所 述 的 一 样 。 简 单 的 方式 是 在 视图 中 直接 
测试 request.user。 例 如 ， 下 述 示 例 检查 用 户 的 电子 邮件 是 否 由 指定 域名 提供 : 














def my_view(request): 
if not request.user.email.endswith('@example.com'): 
return HttpResponse("You can't leave a review for this book.") 
# ... 


更 简单 的 方式 是 使 用 便利 的 user_passes_test 装饰 器 : 


from django.contrib.auth.decorators import user_passes_test 


def email_check(user): 
return user.email.endswith('@example.com') 





es_test(email_check) 


Quser 


def my_view(request): 








user_passes_test() 有 个 必须 指定 的 参数 : 一 个 可 调用 对 象 ， 其 参数 为 一 个 User 对 象 ， 人 允许 用 户 查看 页 面 时 
返回 True。 注 意 ，user_passes_test() 不 自动 检查 用 户 是 不 是 匿名 的 。 这 个 装饰 器 有 两 个 可 选 的 参数 : 



































1. login_url。 指 定 一 个 URL， 把 未 通过 测试 的 用 户 重 定向 到 那里 。 可 以 设 为 登录 页 面 ， 如 果 不 指 定 则 
使 用 LOGIN_URL 的 值 。 

2.， redirect field_name。 与 login_required() 中 的 作用 一 样 。 设 为 None 时 ，URL 中 没有 这 个 查询 字符 
串 参 数 。 如 果 把 用 户 重 定向 到 登录 页 面 之 外 的 页 面 ， 那 就 没有 “下 一 个 页 面 "， 因 此 无 需 这 个 参数 。 












































例如 : 


@user_passes_test(email_check, login_url='/login/') 
def my_view(request): 


permission_required 装饰 器 





检查 用 户 有 没有 特定 权限 是 比较 常见 的 任务 。 鉴 于 此 ，Django 提供 了 一 种 简便 的 方式 一 一 permission_re- 
quired() 装饰 器 : 


from django.contrib.auth.decorators import permission required 


@permission required('reviews.can_vote') 
def my_view(request): 


与 has_perm() 方法 一 样 ， 参 数 名 称 的 形式 为 “<app label>.<permission codename>”( 例 如 ，reviews .can_vote 
是 reviews 应 用 中 某 个 模型 定义 的 权限 ) 。 这 个 装饰 器 的 参数 也 可 以 是 一 个 权限 列表 。 注 意 ，permission_re- 
quired() 也 有 可 选 的 login_url 参数 。 例 如 : 


from django.contrib.auth.decorators import permission required 


@permission_required('reviews.can_vote', login_ url='/loginpage/') 
def my_view(request): 
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与 Login_required() 装饰 器 一 样 ，Login_urtl 的 默认 值 是 LOGIN_URL。 如 果 指 定 了 raise_exception 人 参数， 这 
个 装饰 器 不 会 重 定向 到 登录 页 面 ， 而 是 抛 出 PermissionDenied 异常 ， 显 示 403 (HTTP Forbidden) 视图 。 











修改 密码 后 作废 会 话 








如 果 AUTH_USER_MODEL 继承 自 AbstractBaseUser ， 或 者 定制 了 get_session_auth_hash() 方法 ， 通 过 身份 验证 
的 会 话 包含 这 个 方法 返回 的 哈 希 值 。 对 AbstractBaseUser 来 说 ， 返 回 的 是 密码 字段 的 Hash Message Authenti- 
cation Code (HMAC) 。 











如 果 启 用 了 SessionAuthenticationMiddleware，Django 会 验证 随 各 个 请 求 发 送 的 哈 希 值 是 否 与 服务 器 端 计算 
的 匹配 。 这 样 ， 修 改 密码 后 ， 用 户 的 所 有 会 话 都 会 失效 ， 从 而 退出 。 












































Django 自 带 的 密码 修改 视图 ，django.contrib.auth.views.password_change() 和 django.contrib.auth 中 的 
user_change_password， 在 用 户 修改 自己 的 密码 后 会 使 用 新 的 密码 哈 希 值 更 新 会 话 ， 因 此 不 会 退出 。 如 果 使 用 
自 定义 的 密码 修改 视图 ， 想 具有 类 似 的 行为 ， 使 用 这 个 函数 : 









































django.contrib.auth.decorators.update_session auth_hash(request, user) 














这 个 函数 的 参数 是 当前 请 求 对 象 和 更 新 后 的 用 户 对 象 ， 从 后 一 个 参数 中 获取 新 哈 希 值 后 更 新 会 话 。 示 例 用 法 
如 下 : 














from django.contrib.auth import update_session _auth_hash 


def password_change(request): 
if request.method == 'POST': 
form = PasswordChangeForm(user=request.user, data=request.POST) 
if form.is_valid(): 
form.save() 
update_session_auth_hash(request, form.user) 
else: 




















get_session_auth_hash() 要 使 用 SECRET_KEY， 因 此 更 新 网 站 的 密 钥 后 ， 现 有 会 话 都 会 作废 。 








11.6 身份 验证 视图 














Django 为 登录 、 退 出 和 密码 管理 提供 了 视图 。 这 些 视图 使 用 auth 包 中 内 置 的 表单 ， 不 过 也 可 以 传人 自己 编 
写 的 视图 。Django 没有 为 身份 验证 视图 提供 默认 的 模板 ， 不 过 下 文 将 说 明 各 个 视图 的 模板 上 下 文 。 












































在 项 目 中 使 用 这 些 视图 要 实现 不 同 的 方法 ， 不 过 最 简单 也 是 最 常见 的 做 法 是 把 django.contrib.auth.urls 提 
供 的 URL 配置 添加 到 项 目的 URL 配置 中 。 例 如 : 




















urlpatterns = [url('^', include('django.contrib.auth.urls'))] 


这 样 ， 各 个 视图 在 默认 的 URL 上 (后 文 详 述 ) 。 


























这 些 内 置 的 视图 都 返回 一 个 TemplateResponse 实例 ， 这 样 便于 在 泻 染 之 前 定制 响应 数据 。 多 数 内 置 的 身份 验 
证 视图 提供 了 URL 名 称 ， 易 于 引用 。 
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11.6.1 Login 视图 


登录 用 户 。 





默认 URL: /login/。 


可 选 参数 : 








。 template_name: 这 个 视图 使 用 的 模板 名 称 。 默 认为 registration/login.html。 

。 redirect_fieLd_name: GET 参数 中 指定 登录 后 重 定 向 URL 的 字段 名 称 。 默 认为 next。 

。 authentication_form: 验证 身份 的 可 调用 对 象 (通常 是 一 个 表单 类 ) 。 默 认为 AuthenticationForm。 
。 current_app: 一 个 提示 ， 指 明 当 前 视图 所 在 的 应 用 。 详 情 参 见 7.8.1 市。 


。 extra_context: 一 个 字典 ， 包含 额外 的 上 下 文 数据 ， 随 默认 的 上 下 文 数据 一 起 传 给 模板 。 







































































Login 视图 的 作用 如 下 : 


























。 如 果 通 过 GET 调用 ， 显 示 登 录 表 单 ， 其 目标 地 址 与 当前 URL 一 样 。 稍 后 详 述 。 


。 如 果 通 过 P0ST 调用 ， 发 送 用 户 提交 的 和 凭据， 尝试 登录 用 户 。 如 果 登 录 成 功 ， 重 定向 到 next 指定 的 
URL。 如 果 没 有 next， 重 定向 到 LOGIN_REDIRECT_URL (默认 为 /accounts/profile/) 。 如 果 登 录 失 
败 ， 重 新 显示 登录 表单 。 

































































登录 视图 的 模板 由 你 提供 ， 模 板 文件 默认 名 为 registration/login.html。 
模板 上 下 文 : 





。 form: 表示 AuthenticationForm 的 Form 对 象 。 








。 next: 成 功 登 录 后 重 定向 的 目标 URL。 自 身 可 能 也 包含 查询 字符 串 。 














。 site: 当前 Site,， 根据 SITE_ID 设置 确定 。 如 果 未 安装 网 站 框架 ， 其 值 默 认为 Requestsite 实例 ， 从 
当前 HttpRequest 对 象 中 获取 网 站 名 称 和 域名 。 


site_name: site.name 的 别名 。 如 果 未 安装 网 站 框架 ， 其 值 为 request.META[ 'SERVER_NAME' ] 的 值 。 












































如 果 不 想 把 模板 命名 为 registration/Login.htmL， 可 以 为 URL 配置 提供 额外 的 参数 ， 设 定 tempLate_name 参 


11.6.2 Logout 视图 








退出 用 户 。 
默认 URL: /Logout/ 


可 选 的 参数 : 





。 next_page: 退出 后 重 定向 的 目标 URL。 


























。 template_name: 一 个 模板 全 名 ， 在 用 户 退 出 后 显示 。 如 果 未 提供 这 个 参数 ， 默 认为 registration/ 
Logged_out .html。 





。 redirect_field_name: GET 参数 中 指定 退出 后 重 定向 URL 的 字段 名 称 。 默 认为 next。 如 果 提 供 这 个 参 
数 ，next_page 将 被 覆盖 。 


。 current_app: 一 个 提示 ， 指 明 当 前 视图 所 在 的 应 用 。 详 情 参见 7.8.1 节 。 
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。 extra_context: 一 个 字典 ， 包 含 额外 的 上 下 文 数 据 ， 随 默认 的 上 下 文 数据 一 起 传 给 模板 。 


模板 上 下 文 : 


。 title; 本 地 化 之 后 的 字符 串 “Logged out”。 




















。 site: 当前 Stte， 根 据 SITE_ID 设置 确定 。 如 果 未 安装 网 站 框架 ， 其 值 默 认为 Requestsite 实例 ， 从 


当前 HttpRequest 对 象 中 获取 网 站 名 称 和 域名 。 














。 site_name: site.name 的 别名 。 如 果 未 安装 网 站 框架 ， 其 值 为 request.META['SERVER_NAME ' ] 的 值 。 


11.6.3 Logout_then_Login 视图 

















退出 用 户 ， 然 后 重 定向 到 登录 页 盏 











默认 URL: 未 提供 。 





可 选 的 参数 : 


o 











。 Login_urt: 重 定向 到 的 登录 页 面 的 URL。 如 果 未 提供 ， 默 认为 LOGIN_URL。 


。 current_app: 一 个 提示 ， 指 明 当 前 视图 所 在 的 应 用 。 详 情 参 见 7.8.1 节 。 
























































。 extra_context: 一 个 字典 ， 包 含 额外 的 上 下 文 数 据 ， 随 默认 的 上 下 文 数据 一 起 传 给 模板 。 


11.6.4 password_change 视图 


让 用 户 修改 密码 。 


默认 URL: /password_change/ 


可 选 的 参数 : 














。 template_name: 完整 的 模板 名 称 ， 用 于 显示 密码 修改 表单 。 如 果 未 提供 ， 默 认为 registration/pass- 


word_change_form.htmtL。 


。 post change_redirect. 


。 password_change_form: 


成 功 修改 密码 后 重 定 向 的 目标 URL。 












































自 定义 的 修改 密码 表单 ， 必 须 接受 user 关键 字 参 数 。 这 个 表单 负责 修改 用 户 


的 密码 。 默 认为 PasswordChangeForm。 











。 current_app: 一 个 提示 ， 指 明 当 前 视图 所 在 的 应 用 。 详 情 参见 7.8.1 节 。 






































。 extra_context: 一 个 字典 ， 包含 额外 的 上 下 文 数据 ， 随 默认 的 上 下 文 数据 一 起 传 给 模板 。 


模板 上 下 文 : 




















。 form: 密码 修改 表单 (参见 前 面 的 password_change_form) 。 











11.6.5 password_change_done 视图 








这 个 页 面 在 用 户 修改 密码 后 显示 。 























默认 URL: /password_change_done/ 


可 选 的 参数 : 
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。 template_name: 要 使 





























。 current_app: 一 个 提示 ， 指 明 当 前 视图 所 在 的 应 


。 extra_context: 一 个 字 
































bey 








11.6.6 password_reset 视图 


i 











zh > 十 





bom 



























































| 。 详 情 参 见 7.8.1 方 。 


E 成 一 次 性 链接 ， 发 给 用 户 注 册 时 填写 的 电子 邮件 地 址 ， 让 用 户 重 设 密码 。 




















的 模板 全 名 。 如 果 未 提供 ， 默 认为 registration/password_change_done.html。 


#8， 包含 额外 的 上 下 文 数据 ， 随 默认 的 上 下 文 数据 一 起 传 给 模板 。 





[0 果 系 统 中 没有 用 户 提 供 的 电子 邮件 地 址 ， 这 个 视图 不 发 送 电 子 邮 件 ， 而 且 用 户 也 不 会 看 到 错误 消息 。 这 样 
防止 泄露 信息 ， 防 止 被 潜在 的 攻击 者 利用 。 如 果 想 为 这 种 情况 提供 错误 消息 ， 可 以 定义 PasswordResetForm 
% 子 类 ， 把 它 赋 值 给 password_reset_forn 参数 。 


























密码 被 标记 为 不 可 用 的 用 户 不 允许 请 求 重 设 密码 ， 以 防 使 用 外 部 身份 验证 源 (如 LDAP) 时 误 用 。 注 意 ， 此 


时 用 户 看 不 到 错误 消息 ， 也 不 会 发 送 邮件 ， 这 是 为 了 防止 暴 ; 





默认 URL: /password_reset/ 


可 选 参 数 : 


。 template_name: 完整 的 模板 名 称 ， 用 卫 











外 
车 
态 
le 


word_reset_form.html/ 




















email_template_name: 完整 的 模板 名 称 ， 用 于 生成 玉 











为 registration/password_reset email.html。 




















subject_template_name: 完整 的 模板 名 称 ， 用 于 生成 密码 对 


registration/password_reset_subject.txt。 


password_reset_form: 用 于 获取 请 求 重 设 的 用 户 昌 


必用 户 账户 ，。 


上 有 密码 重 设 链接 的 电子 邮 伯 














重 设 表单 。 如 果 未 提供 ， 默 认为 regtstratton/pass- 

















F。 如 果 未 提供 ， 默 认 











外 设 邮件 的 主题 。 如 果 示 提供， 默认 使 用 


多 电子 邮件 。 默 认为 PasswordResetForm。 


token_generator: 检查 一 次 性 链接 的 类 的 实例 。 默 认为 default_token_generator， 它 是 django.con- 


trib.auth.tokens.PasswordResetTokenGenerator 


的 实例 。 








post_reset_redirect: 成 功 请 求 重 设 密码 之 后 重 定 向 的 目 




















标 URL o 


from_email: 一 个 有 效 的 电子 邮件 地 址 。Django 默认 使 用 DEFAULT_FROM_EMAIL。 

















current_app: 一 个 提示 ， 指 明 当 前 视图 所 在 的 应 
extra_context: 一 个 字典 ， 包 含 额 外 的 上 下 文 数 


























html_email_template_name: 完整 的 模板 名 称 ， 用 于 4 








电子 邮件 。 默 认 不 发 送 HTML 格式 的 电子 邮件 。 








模板 上 下 文 : 









































 。 详 情 参 见 7.8.1 节 。 
据 ， 随 默认 的 上 下 文 数据 一 起 传 给 模板 。 
FE 成 内 容 类 型 为 text/htmt 的 多 部 分 (multipart) 


form: 用 于 重 设 用 户 密 码 的 表单 (参见 上 面 的 password_reset_form) 。 

















电子 邮件 模板 上 下 文 ， 


email: user .email 的 别名 。 


























user: 根据 email 表单 字段 确认 的 当前 用 户 。 只 有 已 激活 用 户 ( 即 User .is_active 的 值 为 True) 才能 




















重 设 密 码 。 





site_name: site.name 的 别名 。 如 果 未 安装 网 站 框架 ， 





其 值 为 request.META['SERVER_NAME' ] 的 值 。 


domain: site.domain 的 别名 。 如 果 未 安装 网 站 框架 ， 其 值 为 request.get_host() 的 值 。 
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protocol: http 或 https。 
uid: base64 编码 的 用 户主 键 。 
token: 检查 重 设 链接 是 否 有 效 的 令 牌 。 




















registration/password_reset_email.html 示例 (电子 邮件 正文 模板 ) : 


Someone asked for password reset for email {{ email }}. Follow the link below: 
{{ protocol}}://{{ domain }}{% urL 'password_reset confirm' uidb64=uid token=token %} 


邮件 主题 模板 也 使 用 上 述 模板 上 下 文 。 主 题 必须 是 单行 纯 文 本 字符 串 。 


11.6.7 password_reset_done 视图 








成 功 把 密码 重 设 链接 发 送 给 用 户 后 显示 的 页 面 。 如 果 password_reset() 视图 没有 设 定 post_reset_redirect 


URL， 




















默认 使 用 这 个 视图 。 








默认 URL: /password_reset_done/ 


如 果 系 统 中 没有 用 户 提 供 的 电子 邮件 地 址 、 用 户 未 激活 或 密码 不 可 用 ， 也 会 把 用 户 重 定向 到 这 
个 页 面 ， 但 是 不 发 送 电子 邮件 。 


可 选 参数 : 














template_name: 要 使 用 的 模板 完整 名 称 。 如 果 未 提供 ， 默 认为 registration/password_re- 
set_done.html, 


current_app: 一 个 提示 ， 指 明 当 前 视图 所 在 的 应 用 。 详 情 参见 7.8.1 节 。 
extra_context: 一 个 字典 ， 包 含 额外 的 上 下 文 数据 ， 随 默认 的 上 下 文 数据 一 起 传 给 模板 。 





























11.6.8 password_reset_confirm 视图 


呈现 输入 新 密码 的 表单 。 


默认 URL: /password_reset_confirm/ 


可 选 参数 : 














uidb64: base64 编码 的 用 户 ID 。 默 认为 None。 
token: 检查 密码 是 否 有 效 的 令 牌 。 默 认为 None。 


template_name: 模板 的 完整 名 称 ， 显 示 密 码 确 认 视 图 。 默 认为 registration/password_reset_con- 
firm.html, 

















token_generator: 检查 密码 的 类 的 实例 。 默 认为 default_token_generator， 它 是 django.con- 
trib.auth. tokens.PasswordResetTokenGenerator 的 实例 。 


set_password_form: 用 于 设 定 密码 的 表单 。 默 认为 SetPasswordForm。 
post_reset_redirect: 重 设 密码 后 重 定 向 的 目标 UREL。 默 认为 None。 
current_app: 一 个 提示 ， 指 明 当 前 视图 所 在 的 应 用 。 详 情 参见 7.8.1 市 。 
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。 extra_context: 一 个 字典 ， 包 含 额外 的 上 下 文 数 据 ， 随 默认 的 上 下 文 数据 一 起 传 给 模板 。 





模板 上 下 文 : 




















。 form: 设 定 新 密码 的 表单 (参见 上 面 的 set_password_form) 。 
。 validlink: 布尔 值 ， 链 接 有 效 (uidb64 和 token 都 检查 ) 或 尚未 使 用 时 为 True。 





11.6.9 password_reset_complete 视图 














呈现 一 个 视图 ， 告 诉 用 户 成 功 修改 了 密码 。 














默认 URL: /password_reset_compLete/ 


可 选 参数 : 





。 template_name: 显示 这 个 视图 的 模板 完整 名 称 。 默 认为 registration/password_reset_com- 
plete.html, 


。 current_app: 一 个 提示 ， 指 明 当 前 视图 所 在 的 应 用 。 详 情 参 见 7.8.1 节 。 
。 extra_context: 一 个 字典 ， 包含 额外 的 上 下 文 数据 ， 随 默认 的 上 下 文 数据 一 起 传 给 模板 。 





















































11.6.10 redirect_to_Login 辅助 函数 








为 了 便于 在 视图 中 实现 所 需 的 访问 限制 ，Django 提供 了 redirect_to_login 辅助 函数 。 它 的 作用 是 重 定 向 到 
登录 页 面 ， 成 功 登 录 后 再 返回 之 前 请 求 的 URL。 





























必要 参数 : 


。 next: 成 功 登 录 后 重 定 向 的 目标 URL。 





可 选 参数 : 


























。 Login_urL: 重 定向 的 登录 页 面 的 URL。 如 果 未 提供 ， 默 认为 LOGIN_URL。 


。 redirect_field_name: 指定 登录 后 重 定 向 的 目标 URL 的 GET 字段 名 称 。 如 果 设 定 ， 履 盖 next。 


























11.6.11 内 置 的 表单 


如 果 不 想 使 用 内 置 的 视图 ， 也 不 想 为 这 些 功能 编写 表单 ， 可 以 使 用 身份 验证 系统 在 django.con- 
trib.auth.forms 中 内 置 的 几 个 表单 ( 表 11-1) 。 


这 些 内 置 的 表单 对 用 户 模 型 有 些 假设 ， 如 果 自 定义 了 用 户 模 型 ， 可 能 要 自己 动手 为 身份 验证 系统 编写 表单 。 
表 11-1，Django 内 置 的 身份 验证 表单 
























































































































































































































































表单 名 说 明 

AdminpasswordChangeForm 在 管理 后 台中 用 于 修改 用 户 密码 的 表单 。 第 一 个 位 置 参数 是 用 户 对 象 。 
AuthenticationForm 登录 表单 。 请 求 对 象 是 第 一 个 位 置 参数 ， 存 储 在 表单 中 ， 供 子 类 使 用 。 
passwordChangeForm 修改 密码 的 表单 。 

passwordResetForm 用 于 生成 并 发 送 带 有 重 设 密码 链接 的 电子 邮件 。 
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( 续 ) 










































































表单 名 说 明 

SetpasswordForm 让 用 户 修改 密码 的 表单 ， 无 需 输入 旧 和 密码 。 
UserChangeForm 在 管理 后 台中 用 于 修改 用 户 信 息 和 权限 的 表单 。 
UserCreationForm 创建 新 用 户 的 表单 。 











11.7 模板 中 的 身份 验证 数据 





使 用 RequestContext 时 ， 当 前 登录 用 户 及 其 权限 可 通过 模板 上 下 文 访问 。 


11.7.1 用 户 





泻 染 模板 的 RequestContext 时 ， 当 前 登录 用 户 ， 不 管 是 User 实例 还 是 AnonymousUser 实例 ， 都 存储 在 模板 变 
量 {{ user 小 中: 


{% if user.is_authenticated %} 

<p>Welcome, {{ user.username }}. Thanks for logging in.</p> 
{% else %} 

<p>Welcome, new user. Please log in.</p> 
{% endif %} 























如 果 使 用 的 不 是 RequestContext， 这 个 模板 上 下 文 变量 不 可 用 。 














11.7.2 权限 














当前 登录 用 户 的 权限 存储 在 模板 变量 {{ perms }} 中 。 它 的 值 是 django.contrib.auth.context_proces- 
sors.PermWrapper 的 一 个 实例 ， 对 模板 友好 。 在 {{ perms }} 对 象 中 ， 单 属性 查找 由 User.has_moduLe_perms 
代理 。 只 要 当前 登录 用 户 在 foo 应 用 中 有 权限 ， 下 述 示例 就 返回 True: 









































{{ perms.foo }} 


























两 层 属性 查找 由 User .has_pernm 代理 。 如 果 当 前 登录 用 户 有 foo.can_vote 权限 ， 下 述 示例 返回 True: 





{{ perms.foo.can_vote }} 





因此 ， 在 模板 中 可 以 使 用 {% if %} 语句 检查 权限 : 





{% if perms .foo %} 
<p>You have permission to do something in the foo app.</p> 
{% if perms.foo.can_vote %} 
<p>You can vote!</p> 
{% endif %} 
{% if perms.foo.can_drive %} 
<p>You can drive!</p> 
{% endif %} 
{% else %} 
<p>You don't have permission to do anything in the foo app.</p> 
{% endif %} 
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此 外 ， 还 可 以 使 用 {% if in 季 语句 检查 权限 。 例 如 : 


{% if 'foo' in perms %} 
{% if 'foo.can_ vote' in perms %} 
<p>In Lookup works, too.</p> 
{% endif %} 
{% endif %} 


11.8 在 管理 后 台中 管理 用 户 


django.contrib.admin 和 django.contrib.auth 都 安装 时 ， 在 管理 后 台 可 以 方便 地 查看 和 管理 用 户 、 分 组 和 权 
限 。 用 户 可 以 像 其 他 Django 模型 那样 创建 和 删除 。 此 外 ， 还 可 以 创建 分 组 ， 并 把 权限 赋予 用 户 或 分 组 。 管理 
后 台 还 存储 着 用 户 编辑 日 志 ， 可 供 查 看 。 








11.8.1 创建 用 户 





在 管理 后 台 的 首页 , “Authentication and Authorization” 部 分 中 有 个 “Users” 链 接 。 点 击 后 看 到 的 是 用 户 管理 界面 
( 图 |! 1-1 ) o 











Nige — 口 x 
DD Select userto change|D x 有 有 汪汪 
€ G 省 | [D127.0.0.1:8000/admin/auth/user/ IO 号 三 
Welcome, admin. View site / Change password / Log out 和 
Home » Authentication and Authorization » Users 
Select user to change 
Q | | Search 
By staff status 
All 
Action:  --------- v| Go | 0of 1] selected Yes 
No 
Username a Emailaddress First name lastname Staff status 
admin nigel@masteringdjango.com © By superuser status 
All 
1 user 


Yes 
No 


By active 


All 
Yes 
No 


11-1，Django 管理 后 台中 的 用 户 管理 界面 





“Add user 页 面 与 管理 后 台 标 准 的 页 面 不 同 ， 要 移 填 写 用 户 名 和 密码 才能 编辑 其 余 的 字段 (图 11-2) 。 


如 果 想 让 用 户 在 Django 管理 后 台 创建 用 户 ， 要 赋予 他 添加 和 修改 用 户 的 权限 ( 即 “Add user" 和 
“Change user" 权 限 ) 。 如 果 用 户 只 有 权 添加 用 户 而 无 权 修改 用 户 ， 他 就 无 法 添加 用 户 。 为 什 

么 ?因为 有 权 添加 用 户 就 能 创建 超级 用 户 ， 如 此 以 来 就 能 修改 其 他 用 户 。 所 以 ， 出 于 安全 考 

虑 ，Dijango 强制 要 求 必须 兼 具 “ 添 加 "和 "修改 "两 个 权限 。 
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Nige 一 口 X 
口 Add user| Django site ad X 用 汪 洒 从 
€ @ 省 | D127.0.0.1:8000/admin/auth/user/add/ 这 QO 了 咀 三 


Welcome, Nigel. View site / Change password / Log out 


Home » Authentication and Authorization » Users » Add user 


Add user 


First, enter a username and password. Then, you'll be able to edit more user options. 





] 





Username: 1 

Required 30 characters Or fewer. Letters, digits and ©@ + only 
Password: 
Password confirmation: 

Enter the same password as above, for verification 


Save and add another| Save and continue editing ED 
图 11-2，Django 管理 后 台 的 添加 用 户 界面 


11.8.2 修改 密码 


管理 后 人 台 不 显示 用 户 的 密码 (数据库 中 也 不 存储 ) ， 但 是 显示 着 存储 的 密码 密 文 。 此 外 ， 还 有 指向 密码 修改 
表单 的 链接 ， 让 管理 员 修改 用 户 的 密码 (图 11-3) 。 


























口 Change user| Django sit= x 
> @ 省 DD 127.0.0.1:8000/admin/auth/user/1/ 6 ' 革 一 


Welcome, admin. View site / Change password / Log out = 


Home ; Authentcabon and Authorization » Users , admin 


Change user 


Username: es 


Reqwired. 30 characters or fewer, Letters, digits and © *+/-/. only 







Password 


R 





n Change the password using this 





Raw passwords are not stored, so thore i 





form 





First name 


Last name 


migelepmasterngdjango-com 


Email address 





图 11-3， 修 改 密码 的 链接 ( 圈 出 部 分 ) 














点 击 那个 链接 后 ， 会 显示 修改 密码 表单 (图 11-4) 。 
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口 Change password: admin Xx 


€ CG 省 127.0.0.1:8000/admin/auth/user/1/password/ OO 唱 三 


Welcome, Nigel. View site / Change password / Log out 
Home » Authentication and Authorization » Users » admin » Change password 


Change password: admin 
Enter a new password for the user admin. 





Password: | 





Password 
(again): 


[TT 


图 11-4，Django 管理 后 台 的 密码 修改 表单 


11.9 密码 管理 





如 非 必要 ， 不 要 重新 实现 密码 管理 功能 ，Django 提供 的 功能 足够 安全 和 灵活 。 本 节 说 明 Django 如 何 存储 密 
码 、 如 何 配置 哈 希 方式 ， 以 及 处 理喻 希 密码 的 实用 工具 。 





























11.9.1 Django 如 何 存储 密码 





Django 提供 了 一 个 灵活 的 密码 存储 系统 ， 默 认 使 用 PBKDF2 算法 。User 对 和 象 的 password 属性 是 这 种 格式 的 
字符 串 : 








<algorithm>$<iterations>$<salt>$<hash> 




















这 是 存储 用 户 密码 的 各 个 部 分 ， 之 间 以 美元 符号 分 隔 。 各 部 分 分 别 是 : 哈 希 算法 、 算 法 的 迁 代 次 数 〈 工 作 系 
数 ) 、 随 机 盐 值 和 最 终 得 到 的 密码 哈 希 值 。 





algorithm 是 Django 支持 的 某 种 单 向 哈 希 (或 称 “ 密 码 存 储 ”) 算法 (参见 下 文 ) 。iterations 是 在 哈 希 值 上 
运用 算法 的 次 数 。salt 是 使 用 的 随机 种 子 ， 而 hash 是 单 向 算法 得 到 的 结果 。Django 默认 使 用 PBKDF2 算法 ， 
得 到 SHA256 哈 希 值 。 这 是 NIST 推荐 使 用 的 密码 增强 机 制 ， 对 多 数 用 户 来 说 足够 了 。 这 种 算法 相当 安全 ， 
需要 用 大 量 时 间 计 算 才能 破解 。 然 而 ， 根 据 具 体 的 需求 ， 你 可 能 想 选 择 其 他 的 算法 ， 甚 至 自己 动手 实现 一 种 
算法 ， 满 足 特殊 的 安全 条 件 。 再 次 说 明 ， 多 数 用 户 无 需 这 么 做 。 如 果 你 不 确定 自己 该 不 该 这 么 做 ， 那 有 可 能 
就 不 需要 。 

















如 果 确 实 需要 这 么 做 ， 请 接着 读 : Django 根据 PASSWORD_HASHERS 设置 选择 算法 。 这 个 设置 的 值 是 一 个 类 列 
表 ， 列 出 你 所 安装 的 Django 支持 的 哈 希 算法 。 其 中 第 一 个 元 素 ( 即 settings.PASSNORD_HASHERS[9]) 用 于 存 
储 密码 ， 其 余 的 都 可 用 于 检查 现 有 密码 。 



































也 就 是 说 ， 如 果 想 使 用 其 他 算法 ， 要 修改 PASSWORD_HASHERS 设置 ， 把 你 选择 的 算法 列 在 第 一 位 。PASS- 
WORD_HASHERS 的 默认 值 如 下 : 











PASSWORD_HASHERS = [ 
"django.contrib.auth.hashers.PBKDF2PasswordHasher ' ， 
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"django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher ' ， 
"django.contrib.auth.hashers.BCryptSHA256PasswordHasher ' ， 


"django.contrib.auth.hashers.BCryptPasswordHasher ' ， 


"django.contrib.auth.hashers.SHA1PasswordHasher ' ， 


"django.contrib.auth.hashers.MD5PasswordHasher ' ， 


"django.contrib.auth.hashers.CryptPasswordHasher ' ， 


] 





因此 ，Django 使 用 PBKDF2 算法 存储 所 有 密码 ， 但 是 支持 使 用 PBKDF2SHA1、bcrypt、SHA1 等 算法 检查 存 


储 的 密码 。 接 下 来 的 几 节 说 明 修 改 这 一 设置 的 常见 方式 。 








11.9.2 让 Django 使 用 bcrypt 





bcrypt 是 一 种 流行 的 密码 存储 算法 ， 专 门 针 对 长 期 存储 的 密码 。Django 默认 没有 使 用 这 个 算法 ， 因 为 需要 第 
三 方 库 。 不 过 ， 因 为 有 很 多 人 想 使 用 ， 所 以 Django 为 bcrypt 提供 了 最 低 的 支持 。 











若 想 把 bcrypt 设 为 默认 的 存储 算法 ， 这 么 做 : 


一 





stall 命令 安装 。 


2.， 修改 PASSWORD_HASHERS 设置 ， 把 BCryptSHA256PasswordHasher 列 在 第 一 位 。 即 ， 把 下 述 代码 放 到 设置 


文件 中 : 


PASSWORD_HASHERS = [ 


安装 bcrypt 库 。 可 以 执行 pip install django[bcrypt] 命令 ， 或 者 下 载 之 后 执行 python setup.py in- 








"django.contrib.auth.hashers.BCryptSHA256PasswordHasher ' ， 


"django.contrib.auth.hashers.BCryptPasswordHasher ' ， 


"django.contrib.auth.hashers.PBKDF2PasswordHasher ' ， 
"django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher ' ， 
"django.contrib .auth.hashers.SHA1PasswordHasher ' ， 


"django.contrib.auth.hashers.MD5PasswordHasher ' ， 


"django.contrib.auth.hashers.CryptPasswordHasher ' ， 


] 





(其 他 元 素 仍 要 放 在 这 个 列表 中 ， 和 否则 Django 不 会 更 新 密码 。 人 参见 下 文 。) 




















高 定 ! 现在 Django 将 使 用 bcrypt 为 默认 的 存储 算法 。 








BCryptPasswordHasher 会 截断 密码 


按 设 计 ，bcrypt 在 第 72 个 字符 处 截断 密码 ， 这 意味 着 bcrypt(password_with_100_chars) == bcrypt(pass- 
word_with_166_chars[:72])。BCryptPasswordHasher 没有 做 特殊 处 理 ， 因 此 也 遵守 这 个 隐秘 的 密码 长 度 限 





到 


制 。BCryptSHA256PasswordHasher 打破 了 这 一 限 秆 
被 截断 ， 因 此 是 首选 。 截 断 的 实际 后 果 不 太 严 重 ， 因 为 多 














暴力 破解 bcrypt 所 需 的 时 间 也 是 天 文 数字 。 尽 管 如 此 ， 书 


SHA256PasswordHasher。 


11.9.3 其 他 bcrypt 实现 

















数 用 








， 它 首先 使 用 sha256 计算 密码 的 哈 希 值 。 这 样 能 避免 密码 





户 的 密码 不 会 超过 72 个 字符 ， 即 便 被 截断 了 ， 











\ 心 驶 得 万 年 船 "， 我 们 还 是 推荐 使 用 BCrypt- 

















在 Django 中 使 用 bcrypt 还 有 其 他 方式 ， 但 是 Django 对 bcrypt 的 支持 不 直接 支持 那些 方式 。 为 了 升级 密码 ， 
需要 把 数据 库 中 的 哈 希 值 修改 成 bcrypt$(raw bcrypt output) 格式 。 
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11.9.4 增加 工作 系数 








PBKDF2 和 bcrypt 算法 会 对 哈 希 值 多 次 人 送 代 ， 这 人 么 做 是 为 了 拖延 攻击 者 ， 让 破解 哈 希 密码 的 难度 更 大 。 然 
而 ， 随 着 计算 机 能 力 的 增强 ， 迷 代 的 次 数 应 随 之 增加 。 


Django 开发 团队 选择 了 一 个 合理 的 默认 值 (每 次 发 布 Django 新 版 都 会 增加 ) ， 不 过 你 可 能 想 根据 自己 的 安 
全 需求 和 可 用 的 处 理 能 力 调 大 或 调 小 。 为 此 ， 要 定义 相应 算法 的 子 类 ， 然 后 覆盖 tterations 属性 。 


例如 ， 增 加 默认 的 PBKDF2 算法 的 迭代 次 数 的 步骤 如 下 : 























1. 定义 django.contrib.auth.hashers.PBKDF2PasswordHasher 的 子 类 ; 


from django.contrib.auth.hashers import PBKDF2PasswordHasher 


class MyPBKDF2PasswordHasher(PBKDF2PasswordHasher ) : 
iterations = PBKDF2PasswordHasher.iterations * 100 


2. 把 这 个 类 保存 在 项 目 中 的 某 个 位 置 。 例 如 ， 可 以 放 在 myproject/hashers.py 文件 中 。 
3， 把 自 定 义 的 哈 希 类 设 为 PASSWORD_HASHERS 中 的 第 一 个 元 素 : 























PASSWORD_HASHERS = [ 
"myproject.hashers.MyPBKDF2PasswordHasher ' ， 
"django.contrib.auth.hashers.PBKDF2PasswordHasher ' ， 
# ...# 

] 





结束 ! 现在 ， 你 的 Django 在 使 用 PBKDF2 算法 时 将 大 代 更 多 次 。 





11.9.5 密码 升级 


用 户 登 录 时 ， 如 果 密 码 不 是 以 选中 的 算法 存储 的 ，Django 会 自动 使 用 新 算法 升级 密码 。 这 意味 着 ， 旧 的 
Django 应 用 程序 能 在 用 户 登 录 时 变 得 更 安全 ， 也 意味 着 你 可 以 随时 切换 为 新 推出 的 (和 更 好 的 ) 存储 算法 。 






































然而 ，Django 只 会 对 PASSWORD_HASHERS 中 列 出 的 算法 进行 升级 ， 因 此 ， 换 用 新 算法 时 一 定 不 能 把 旧 的 算法 从 
列表 中 删除 。 如 若 不 然 ， 使 用 列表 中 没有 的 算法 存储 的 密码 将 无 法 升级 。 修 改 PBKDF2 算法 的 迭代 次 数 后 也 
会 升级 密码 。 





11.9.6 手动 管理 用 户 的 密码 





django.contrib.auth.hashers 模块 提供 了 一 系列 用 于 创建 和 验证 哈 希 密码 的 函数 。 这 些 函 数 可 以 独立 于 User 
模型 使 用 。 








如 果 想 自己 动手 比较 纯 文本 密码 和 数据 库 中 的 密码 哈 希 值 ， 使 用 check_password() 函数 。 它 有 两 个 参数 : 要 
检查 的 纯 文本 密码 和 数据 库 中 password 字段 的 值 。 如 果 二 者 匹配 ， 返 回 True， 和 否则 返回 False。 


























make_password() 根据 应 用 程序 使 用 的 算法 创建 哈 希 密码 。 它 有 一 个 必要 的 参数 ， 即 纯 文本 密码 。 























如 果 不 想 使 用 默认 值 (PASSWORD_HASHERS 设置 中 的 第 一 个 元 素 ) ， 还 可 以 提供 一 个 规 值 和 哈 希 算法 。 目 前 支 
持 的 算法 有 : 'pbkdf2_sha256'、'pbkdf2_shal'、'bcrypt_sha256'、'bcrypt'、'shal'’、'md5'、'unsalt- 
_md5' (只 是 为 了 向 后 兼容 ) 和 'crypt' (要 安装 crypt 库 ) 。 








[0 
S 














如 果 密 码 参 数 的 值 是 None， 返 回 一 个 不 可 用 的 密码 (绝对 通 不 过 check_password() 的 检查 ) 。 
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is_password_usable() 检查 指定 字符 串 是 不 是 可 能 通过 check_password() 验证 的 哈 希 密码 。 


11.10 自 定义 身份 验证 














多 数 情 况 下 ，Django 自 带 的 身份 验证 系统 足够 用 了 ， 但 是 开 箱 即 用 的 默认 系统 可 能 无 法 满足 你 的 需求 。 若 想 
定制 ， 你 要 了 解 自 带 系 统 的 哪些 部 分 是 可 扩展 的 或 可 蔡 换 的 。 


身份 验证 后 端 提供 了 一 个 可 扩展 的 系统 ， 以 防 你 想 使 用 别 的 服务 验证 User 模型 存储 的 用 户 名 和 密码 。 你 可 以 
为 模型 赋予 其 他 权限 ， 然 后 使 用 Django 的 权限 核准 系统 检测 。 你 可 以 扩展 默认 的 User 模型 ， 或 者 完全 蔡 换 
成 自 定义 的 模型 。 

















































































































11.10.1 其 他 身份 验证 源 
时 ， 可 能 需要 连接 其 他 身份 验证 源 ， 即 用 户 名 、 密 码 和 身份 验证 方法 来 自 别 处 。 


例如 ， 你 的 公司 可 能 已 经 搭建 好 了 LDAP， 用 于 存储 每 个 员工 的 用 户 名 和 和 密码。 如 果 分 别 为 LDAP 和 Django 
开发 的 应 用 程序 提供 一 套 账户 ， 对 网 络 管理 员 和 用 户 自身 都 是 件 麻烦 事 。 


考虑 到 这 种 情况 ，Django 身份 验证 系统 支持 连接 其 他 身份 验证 源 。 你 可 以 覆盖 Django 默认 基于 数据 库 的 模 
式 ， 或 者 把 默认 系统 与 其 他 系统 连接 起 来 。 





































































































11.10.2 指定 身份 验证 后 端 


Django 在 背后 维护 着 一 个 用 于 验证 身份 的 后 端 列 表 。 调 用 authenticate() 时 (参见 11.5.1 节 ) ，Django 在 
所 有 身份 验证 后 端 中 一 一 尝试 。 如 果 第 一 个 后 端 验证 失败 ， 再 试 第 二 个 ， 然 后 一 直下 去 ， 直 到 试 完 所 有 后 端 
为 止 。 


身份 验证 后 端 列表 由 AUTHENTICATION_BACKENDS 设置 指定 。 它 的 值 是 一 个 Python 路 径 名 列表 ， 指 向 知道 如 何 
验证 身份 的 Python 类 。 这 些 类 可 以 在 Python 路径 中 的 任何 位 置 。AUTHENTICATION_BACKENDS 的 默认 值 为 : 

































































[ django.contrib.auth.backends.ModeLBackend ' ] 














这 是 一 个 基本 的 身份 验证 后 端 ， 检 查 Django 用 户 数据 库 ， 并 查询 内 置 的 权限 。 这 个 后 端 无 法 防范 暴力 破解 攻 
击 ， 因 为 没有 提供 频率 限制 机 制 。 你 可 以 在 自 定 义 的 权限 核准 后 端 中 实现 这 一 机 制 ， 或 者 使 用 多 数 Web 服务 
器 提供 的 机 制 。AUTHENTICATION_BACKENDS 罗列 元 素 的 顺序 是 重要 的 ， 如 果 用 户 名 和 密码 能 通过 多 个 后 端的 验 
证 ， 首 次 发 现 匹 配 后 就 会 停止 。 如 果 后 端 抛 出 PermissionDenied 异常 ， 身 份 验证 立即 失败 ，Django 不 再 使 用 
后 面 的 后 端 检 查 。 


通过 身份 验证 后 ，Django 在 用 户 的 会 话 中 存储 通过 验证 的 是 哪个 后 端 。 在 会 话 持续 的 时 间 内 ， 只 要 需要 访问 
通过 验证 的 用 户 ， 就 使 用 会 话 中 的 后 端 。 这 其 实意 味 着 ， 每 个 会 话 会 缓存 身份 验证 源 ， 所 以 如 果 修 改 了 AU- 
THENTICATION_BACKENDS， 若 想 使 用 其 他 方法 重新 验证 用 户 的 身份 ， 要 清空 会 话 数据 。 为 此 ， 一 个 简单 的 方法 
是 调用 Session.objects.aLL().deLete()。 


























































































































































































































11.10.3 编写 一 个 身份 验证 后 端 








身份 验证 后 端 通过 类 定义 ， 必 须 实 现 两 个 方法 ， 即 get_user(user_id) 和 authenticate(**credentials)， 此 
外 还 有 一 些 可 选 的 权限 核准 方法 。get_user 的 参数 user_id 可 以 是 用 户 名 和 数据 库 中 的 ID 等 ， 不 过 必须 是 
User 对 象 的 主键 。get_user 的 返回 值 是 一 个 User 对 象 。authenticate 的 参数 是 通过 关键 字 参 数 指定 的 赁 
据 。 多 数 时 候 ，authenticate 方法 是 下 面 这 样 : 


























class MyBackend(object): 
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def authenticate(self, username=None, password=None): 
# 检查 用 户 名 和 和 密码， 返回 一 个 User 对 象 


不 过 ， 也 可 以 验证 令 牌 ， 如 下 所 示 : 


class MyBackend(object): 


不 管 怎 相 


def authenticate(self, token=None): 
# 检查 令 牌 ， 返回 一 个 User 对 象 


，authenticate 都 应 该 检查 传人 的 和 凭据， 通过 检查 时 返回 对 应 的 User 对 象 。 





回 None。 








Django 管理 后 台 与 本 章 开头 描述 的 User 对 象 紧密 耦合 。 














如 果 检 查 失 败 ， 应 该 返 


目前 ， 最 佳 处 理 方式 是 为 后 端 (如 LDAP 目录 、 外 部 SQL 数据 库 ， 等 等 ) 里 的 各 个 用 户 创建 一 个 Django 


User 对 象 。 你 可 以 编写 一 个 脚本 事先 创建 好 ， 也 可 以 在 用 户 首次 登录 时 让 authenticate 方法 创建 。 
下 面 的 示例 后 端 验 记 


象 : 





























from django.conf import settings 


from django.contrib.auth.models import User, check_password 


class SettingsBackend(object): 


Authenticate against the settings ADMIN_LOGIN and ADMIN_PASSWORD. 
Use the login name, and a hash of the password. For example: 


ADMIN_LOGIN = 'admin' 
ADMIN_PASSWORD = 'shal$4e987$afbcf42e21bd417fb71db8c66b321e9fc33051de' 


def authenticate(self, username=None, password=None): 
login valid = (settings.ADMIN_LOGIN == username) 
pwd_valid = check_password(password, settings.ADMIN PASSWORD) 
if login valid and pwd_valid: 
try: 
User = User .objects.get(username=username) 
except User .DoesNotExist: 
# 新 建 用 户 
# 注意 ， 可 以 把 密码 设 为 任何 值 ， 因 为 不 会 检查 它 
# 检查 的 是 settings.py 文件 中 定义 的 密码 
User = User(uysername=username, password='password') 
User .is_staff = True 
User .is_superuser = True 
User .save() 
return user 
return None 


def get user(self, user_id): 
Cry 
return User.objects.get(pk=user_id) 








F settings .py 文件 中 定义 的 用 户 名 和 密码 ， 在 首次 验证 用 户 的 身份 时 创建 Django User 对 
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except USser .DoesNotEXxist: 
return None 


11.10.4 在 自 定义 后 端 中 核准 权限 








自 定 义 的 权限 核准 后 端 可 以 提供 自己 的 权限 。 用 户 模 型 会 把 权限 查找 函数 (get_group_permissions()、 
get_all_permissions()、has_perm() 和 has_module_perms()) 委托 给 实现 了 这 些 函 数 的 身份 验证 后 端 。 赋 予 
用 户 的 权限 将 是 所 有 后 端 返 回 的 全 部 权限 的 超 集 。 即 ，Django 为 用 户 赋予 每 个 后 端 定义 的 权限 。 












































如 果 后 端 在 has_perm() 或 has_module_perms() 函数 中 抛 出 PermissionDenied 异常 ， 权 限 核准 立即 失败 ， 
Django 不 会 检查 后 面 的 后 端 。 前 面 那个 示例 后 端 可 以 轻易 实现 管理 员 权 限 : 















































class SettingsBackend(object): 


def has_perm(self, user_obj, perm, obj=None): 
if user_obj.username == settings.ADMIN_LOGIN: 
return True 
else: 
return False 








这 为 上 述 示例 中 获准 访问 的 用 户 赋予 完整 的 权限 。 注 意 ， 除 了 User 模型 相关 函数 的 那些 参数 之 外 ， 后 端的 权 
限 核准 函数 还 都 接受 用 户 对 象 (可 以 是 匿名 用 户 ) 为 参数 。 



































django/contrib/auth/backends.py 文件 中 的 ModelBackend 类 完整 实现 了 权限 核准 后 端 。 这 是 默认 的 后 端 ， 多 
数 时 候 查 询 的 是 auth_permission 表 。 如 果 只 想 自 定 义 后 端 API 的 部 分 行为 ， 可 以 利用 Python 继承 ， 定 义 
ModelBackend 的 子 类 ， 而 不 是 在 自 定义 的 后 端 中 实现 全 部 API。 


























11.10.5 核准 匿名 用 户 的 权限 
































匿名 用 户 是 未 验证 身份 的 用 户 ， 即 没有 提供 有 效 的 身份 验证 信息 。 然 而 ， 这 并 不 意味 着 匿名 用 户 没 权 限 做 任 
何事 。 基 本 上 ， 多 数 网 站 允许 匿名 用 户 浏 览 大 部 分 页 面 ， 而 且 还 有 -一些 网 站 允许 匿名 用 记 ! 发 表 评 论 等 。 










































































Django 的 权限 框架 无 法 存储 匿名 用 户 的 权限 。 然 而 ， 传 给 身份 验证 后 端的 用 户 对 象 可 能 是 django.con- 
trib.auth.models.AnonymousUser 的 实例 ， 因 此 可 以 为 匿名 用 户 指 定 自 定义 的 权限 核准 行为 。 


这 对 可 复 用 应 用 的 开发 者 来 说 尤其 有 用 ， 他 们 可 以 把 所 有 权限 核准 交 给 身份 验证 后 端 ， 而 不 用 控制 匿名 访 
问 。 
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11.10.6 核准 未 激活 用 户 的 权限 


未 激活 的 用 户 是 已 经 验证 了 身份 、 但 是 is_active 属性 被 设 为 False 的 用 户 。 然 而 ， 这 并 不 意味 着 未 激活 的 
用 户 没 权限 做 任何 事 。 例 如 ， 人 允许 他 们 激活 自己 的 账户 。 







































































权限 系统 对 匿名 用 户 的 支持 允许 匿名 用 户 有 的 权限 而 未 激活 的 用 户 没 有 。 别 筷 了 在 后 端的 权限 核准 方法 中 测 
试用 户 的 is_active 属性 。 

















11.10.7 处 理 对 象 的 权限 























Django 的 权限 框架 为 对 象 的 权限 建立 了 基础 ， 但 是 没有 在 核心 中 实现 。 这 意味 着 ， 对 对 象 权限 的 检查 始终 返 
回 False 或 空 列表 (取决 于 检查 的 对 象 ) 。 核 准 对 象 权 限 的 每 个 方法 都 接受 关键 字 参 数 obj 和 user_obj， 可 
以 返回 相应 的 对 象 级 权限 。 
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11.11 自 定义 权限 








若 想 为 指定 的 模型 对 象 自 定 义 权限 ， 使 用 模型 中 Meta 类 的 permissions 属性 。 下 述 Task 模型 自 定义 了 三 个 权 
限 ， 分 别 是 用 户 可 在 应 用 程序 内 对 Task 实例 能 做 或 不 能 做 的 操作 : 





class Task(models.Model): 


class Meta: 
permissions = ( 
("view task", "Can see available tasks"), 
("change_task_status", "Can change the status of tasks"), 
("close_task", "Can remove a task by setting its status as 
closed"), 


) 











这 么 做 的 唯一 作用 是 在 执行 manage.py migrate 命令 时 创建 这 些 额 外 的 权限 。 用 户 尝试 访问 应 用 程序 提供 的 
功能 时 (查看 任务 、 修 改 任务 的 状态 或 关闭 任务 ) ， 要 在 代码 中 检查 这 些 权 限 的 值 。 接 着 上 例 ， 下 述 代码 检 
查 用 户 可 不 可 以 查看 任务 : 





user.has_perm('app.view task') 


11.12 扩展 现 有 的 User 模型 


除了 把 默认 的 User 模型 替换 掉 ， 还 有 两 种 扩展 它 的 方式 。 如 果 你 想 做 的 修改 只 是 行为 上 的 ， 不 需要 修改 数据 
库 中 存储 的 数据 ， 可 以 基于 User 创建 一 个 代理 模型 。 这 样 能 得 到 代理 模型 提供 的 各 个 功能 ， 如 默认 的 排序 、 
自 定 义 管理 需 或 自 定义 模型 方法 。 


如 果 想 存储 关于 用 户 的 额外 信息 ， 可 以 与 另 一 个 模型 建立 一 对 一 关系 ， 把 信息 存储 在 那个 模型 的 字段 中 。 这 
种 通过 一 对 一 关系 连接 的 模型 通常 称 为 个 人 资料 模型 (profile model) ， 因 为 它 可 能 存储 着 与 身份 验证 无 关 的 
言 息 。 比 如 说 ， 可 以 创建 下 述 Employee 模型 ; 





























from django.contrib.auth.models import User 


class Employee(models.Model): 
User = models.OneToOneField(User) 
department = models.CharField(max_length=100) 








假如 员工 Fred Smith 既 属于 User 模型 ， 也 属于 Employee 模型 ， 可 以 使 用 Django 标准 的 相关 模型 约定 访问 额 
外 的 信息 : 








>>> U = User .objects.get(username='fsmith') 
>>> freds_department = U.empLoyee.department 











若 想 把 个 人 资料 模型 中 的 字段 添加 到 管理 后 台中 的 用 户 页 面 中 ， 在 应 用 的 admin.py 文件 中 定义 一 个 In- 
LineModeLAdmin 类 (这 里 使 用 的 是 StackedInline) ， 然 后 把 它 添加 到 UserAdmin 类 中 ， 再 注册 到 User 类 上 : 












































from django.contrib import admin 
from django.contrib.auth.admin import UserAdmin 
from django.contrib.auth.models import User 


from my_user_profile app.models import Employee 


# 为 Employee 模型 定义 一 个 内 联 管理 后 台 描 述 符 
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# 它 的 行为 有 点 像 单 例 

class EmployeeInline(admin.StackedInline): 
model = Employee 
can_delete = False 
verbose name_plural = "empLoyee' 


# 定义 一 个 UserAdmin 的 子 类 
class UserAdmin(UserAdmin): 
inlines = (EmployeeInline, ) 


# 重新 注册 UserAdmin 
admin.site.unregister(User) 
admin.site.register(User, UserAdmin) 

















个 人 资料 模型 没什么 特殊 的 ， 就 是 普通 的 Django 模型 ， 只 是 碰巧 与 User 模型 有 一 对 一 关系 。 因 此 ， 创 建 用 
户 时 不 会 自动 创建 对 应 的 个 人 资料 ， 不 过 可 以 通过 django.db.models.signals.post_save 信号 创建 或 更 新 相 
关 的 模型 。 


注意 ， 通 过 相关 的 模型 检索 数据 时 有 额外 的 查询 或 联结 ， 某 些 情况 下 替换 User 模型 或 添加 额外 的 字段 可 能 
好 。 然 而 ,项目 中 的 应 用 对 默认 User 模型 的 现 有 链接 可 能 会 调整 额外 的 数据 库 负载 。 























11.13 替换 成 自 定义 的 User 模型 


对 有 些 项 目 来 说 ，Django 内 置 的 User 模型 可 能 无 法 满足 身份 验证 的 需求 。 例 如 ， 较 之 用 户 名 ， 有 些 网 站 更 
适合 使 用 电子 邮件 地 址 作为 用 户 的 唯一 标识 符 。Django 允许 覆盖 默认 的 User 模型 ， 方 法 是 把 AUTH_USER_MOD- 
EL 设置 的 值 设 为 自 定义 的 模型 ; 


AUTH_USER_MODEL = "books.MyUser 











点 号 前 面 是 Django 应 用 的 名 称 (必须 在 INSTALLED_APPS 设置 中 列 出 ) ， 后 面 是 想 用 作 User 模型 的 Django 模 
型 名 oo 


提醒 
修改 AUTH_USER_MODEL 设置 对 Django 项 目 有 重大 的 影响 ， 尤 其 是 数据 库 结 构 。 如 果 在 运行 迁移 


之 后 修改 AUTH_USER_MODEL， 必 须 自己 动手 更 新 数据 库 ， 因 为 很 多 数据 库 表 的 关系 受到 了 影 
啊 。 除 非 有 特别 好 的 理由 ， 和 否则 不 要 修改 AUTH_USER_MODEL。 








尽管 我 在 上 面 做 出 了 提醒 ， 但 是 要 知道 Django 是 完全 支持 自 定义 用 户 模型 的 。 具 体 做 法 超出 了 本 书 范畴 。 兼 
容 管理 后 台 的 完整 示例 ， 以 及 对 如 何 自 定义 用 户 模型 的 全 面 说 明 ， 参 见 Django Project 网 站 。 














11.14 接 下 来 


本 章 学 习 了 Django 的 用 户 身 份 验证 系统 、 内 置 的 身份 验证 工具 ， 以 及 大 量 可 定制 的 功能 。 下 一 章 探讨 算得 上 
是 创建 和 维护 强健 的 应 用 最 为 重要 的 一 个 工具 一 一 自动 化 测试 。 











178 -第 11 章 在 Django 中 验证 用 户 的 身份 





第 12 章 测试 Django 应 用 程序 


12.1 测试 简介 














与 所 有 成 熟 的 框架 一 样 ，Django 也 内 置 了 单元 测试 功能 。 单 元 测试 是 一 种 软件 测试 过 程 ， 测 试 的 是 软件 应 用 
程序 的 独立 单元 ， 确 保 能 做 预期 中 的 事情 。 


单元 测试 分 为 不 同 的 层级 ， 可 以 测试 单个 方法 ， 看 它 能 不 外 
测试 整个 方法 组 件 ， 确 保 一 系列 用 户 输 入 能 得 到 所 需 的 结 


在 单元 测试 背后 ， 有 四 个 基本 的 概念 : 


























un 









































返回 正确 的 值 以 及 能 否 处 理 正确 的 数据 ， 也 可 以 






































ny 
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1.， 测试 固件 (test fixture) ,执行 测试 所 需 的 设置 。 包 含 数 据 库 、 示 例 数 据 集合 服务 器 搭建 。 测 试 固件 可 
能 还 包括 测试 完毕 后 执行 的 清理 操作 。 


I 试用 例 (test case) ， 测 试 的 基本 单元 。 测 试用 例 检 查 指 定 的 输入 是 否 能 得 到 预期 的 结果 。 
测试 组 件 test suite) ， 一 系列 测试 用 例 或 其 他 测试 组 件 ， 作 为 一 个 整体 执行 。 
测试 运行 程序 (test runner) ， 负 责 执 行 测试 并 把 结果 反馈 给 用 户 的 软件 程序 。 
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软件 测试 是 一 门 很 深 的 学 问 ， 涉 及 众多 知识 ， 本 章 只 是 对 单元 测试 做 个 简略 介绍 。 网 上 有 大 量 关 于 软件 测试 
理论 和 方法 的 资源 ， 我 建议 你 研读 一 下 。 若 想 深入 了 解 Django 采用 的 单元 测试 方法 ， 请 访问 Django Project 
网 站 。 



































12.2 自动 化 测试 简介 


12.2.1 自动 化 测试 是 什么 


你 可 能 没 注意 到 ， 本 书 前 面 已 经 编写 了 测试 代码 。 在 Django shell 中 确认 函数 是 否 可 用 ， 或 者 看 给 定 的 输入 
能 得 到 什么 输出 ， 这 就 是 在 测试 你 的 代码 。 例 如 ， 在 第 2 章 ， 我 们 把 一 个 字符 串 传 给 期 竺 整数 的 视图 ， 那 个 


到 抛 出 TypeError 异常 。 
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测试 是 应 用 程序 开发 的 常规 组 成 部 分 ， 不 过 自动 化 测试 的 不 同 之 处 是 ， 测 试 工作 由 系统 代劳 。 编 写 一 系列 测 
试 之 后 ， 如 果 修 改 了 应 用 ， 可 以 检查 代码 是 否 还 能 像 之 前 那样 工作 ， 而 不 用 每 次 都 花 时 间 自 己 动手 测试 。 


12.2.2 为 什么 测试 











如 果 你 所 做 的 Django 编程 工作 只 是 创建 一 个 像 本 书 中 那样 的 简单 应 用 程序 ， 确 实 ， 你 无 需 知道 如 何 编写 自动 
化 测试 。 但 是 ， 如 果 你 想 成 为 专业 的 程序 员 ， 想 开发 更 复杂 的 项 目 ， 必 须要 知道 如 何 编写 自动 化 测试 。 


自动 化 测试 有 以 下 优点 : 












































。 节省 时 间 。 手 动 测试 大 型 应 用 程序 各 组 件 之 间 庞 杂 的 交互 浪费 时 间 ， 而 且 易 于 出 错 。 自 动 化 测试 能 节 
省 时 间 ， 让 你 专注 编程 。 


。 进 免 出 问题 。 测 试 能 强调 代码 的 内 部 运作 ， 让 你 发 现 什么 地 方 存在 错误 。 
。 看 起 来 专业 。 专 业 人 士 都 编写 测试 。Django 最 初 的 开发 者 之 一 Jacob Kaplan-Moss 说 ;“ 没 有 测试 的 代 
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码 先 天 不 足 。” 
。 增进 团队 协作 。 测 试 能 保证 同事 不 会 意外 破坏 你 的 代码 (你 自己 也 不 会 不 小 心 破坏 别人 的 代码 ) 。 


12.3 基本 的 测试 策略 


编写 测试 的 方式 很 多 。 有 些 程序 员 遵 守 一 个 称 为 测试 驱动 开发 〈Test-Driven Development，TDD) 的 准则 ， 
先 写 测试 后 写 代 码 。 看 上 去 这 可 能 有 点 违背 直觉 ， 但 是 其 实 多 数 人 通常 都 是 这 么 做 的 : 先 描述 问题 ， 再 编写 
解决 问题 的 代码 。 


测试 驱动 开发 为 Python 测试 用 例 的 编写 定 下 了 基调 。 通 常 ， 测 试 新 手 会 先 编写 代码 ， 然 后 再 判断 是 否 应 该 编 
写 测试 。 其 实 ， 早 点 编写 测试 或 许 更 好 ， 但 是 何 时 着 手 都 不 晚 。 













































































12.4 编写 一 个 测试 





在 开始 编写 首 个 测试 之 前 ， 我 们 先 在 Book 模型 中 引入 一 个 缺陷 。 








比如 说 我 们 决定 在 Book 模型 中 自 定义 一 个 方法 ， 指 明 一 本 书 是 不 是 最 近 出 版 的 。Book 模型 可 以 像 这 样 定 
义 : 








import datetime 
from django.utils import timezone 


from django.db import models 


class Book(models.Model): 
title = models.CharField(max_length=100) 
authors = models.ManyToManyField(Author) 
publisher = models.ForeignKey(Publisher) 
publication date = modeLs.DateFieLd() 


def recent publication(self): 
return self.publication date >= timezone.now().date() - datetime.timedelta(weeks=8) 


## ...# 





首先 ， 导 入 两 个 模块 : Python 标准 库 中 的 datetime 和 django.utils 中 的 tinezone。 这 是 计算 日 期 所 需 的 。 
然后 ， 在 Book 模型 中 定义 一 个 名 为 recent_publication 的 方法 ， 计 算 8 周 前 的 日 期 ， 当 图 书 的 出 版 日 期 晚 于 
那 一 天 时 返回 True。 


下 面 我 们 打开 交互 式 shell， 测 试 一 下 这 个 新 方法 : 




















python manage.py shell 


>>> from books.models import Book 

>>> import datetime 

>>> from django.utils import timezone 
>>> book = Book.objects.get(id=1) 

>>> book.title 

'Mastering Django: Core' 

>>> book.publication date 
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datetime.date(2016, 5, 1) 
>>>book .publication date >= timezone.now().date() - datetime.timedelta(weeks=8) 
True 





目前 来 看 没什么 问题 ， 我 们 先导 入 Book 模型 ， 然 后 检索 一 本 书 。 今 天 是 2016 年 6 月 11 日 ， 我 在 数据 库 中 填 
写 的 出 版 日 期 是 5 月 1 日， 在 8 周 的 范围 内 ， 因 此 这 个 方法 正确 地 返回 了 True。 


显然 ， 你 自己 测试 时 要 修改 出 版 日 期 ， 这 样 测试 才能 得 到 上 述 结果 。 
现在 ， 我 们 把 出 版 日 期 设 为 未 来 的 某 一 天 ， 比 如 9 月 1 日， 看 看 会 发 生 什么 : 















































>>> book.publication_date 

datetime.date(2016, 9, 1) 

>>>book.publication date >= timezone.now().date() - datetime.timedelta(weeks=8) 
True 

















不 妙 ， 这 里 显然 有 问题 。 你 应 该 很 快 就 能 在 逻辑 中 发 现 错 误 一 一 任何 晚 于 8 周 前 那 一 天 的 日 期 都 返回 True， 
包括 未 来 的 日 期 。 








Wass 








造 的 示例 ， 不 过 撤 开 这 一 点 不 管 ， 下 面 来 为 这 个 有 问题 的 逻辑 编写 一 个 测试 。 























12.4.1 编写 测试 











使 用 Django 的 startapp 命令 创建 books 应 用 时 ， 它 在 应 用 的 目录 中 创建 了 一 个 名 为 tests.py 的 文件 。 这 个 
文件 用 于 保存 books 应 用 的 测试 。 打 开 那 个 文件 ， 编 写 一 个 测试 : 









































import datetime 

from django.utils import timezone 
from django.test import TestCase 
from .models import Book 


class BookMethodTests(TestCase): 


def test recent pub(self): 
recent_publication() should return False for future publication 
dates. 


futuredate = timezone.now().date() + datetime.timedelta(days=5) 
future_pub = Book(publication_date=futuredate) 
self.assertEqual(future_pub.recent_publication(), False) 





这 上段 代码 十 分 简单 ， 基 本 上 与 前 面 在 Django shell 中 所 做 的 一 样 。 唯 一 的 不 同 是 ， 现 在 我 们 把 测试 代码 封装 
在 一 个 类 中 ， 而 且 创 建 了 一 个 断言 (assertion) ,使 用 未 来 的 日 期 测试 recent_publication() 方法 。 





























本 章 后 文 会 详细 介绍 测试 类 和 assertEqual 方法 ， 现 在 我 们 的 目的 只 是 了 解 测试 的 基本 结构 。 





12.4.2 运行 测试 




















写 好 测试 之 后 要 运行 。 幸好， 这 并 不 难 。 打 开 终 端 ， 输 入 下 述 命令 : 








python manage.py test books 
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稍 等 片刻 ，Django 应 该 输出 类 似 下 面 的 内 容 : 








Creating test database for alias 'default'... 


Traceback (most recent call last): 
File "C:\Users\Nigel\ ... mysite\books\tests.py", line 25, in test_recent_pub 
self.assertEqual(future_pub.recent_ publication(), False) 
AssertionError: True != False 


Ran 1 test in 0.000s 


FAILED (failures=1) 
Destroying test database for alias 'default'... 


上 述 过 程 详 述 如 下 : 





。 python manage.py test books 命令 在 books 应 用 中 查找 测试 。 
。 找到 django.test.TestCase 类 的 一 个 子 类 。 

。 为 测试 创建 一 个 特殊 的 数据 库 。 
。 查找 名 称 以 “test* 开 头 的 方法 。 
。 在 test_recent_pub 中 ,创建 一 个 Book 实例 ， 把 publication_date 属性 设 为 5 天 后 的 日 期 。 

。 调用 assertEqual() 方 法， 发现 那个 实例 的 recent_publication() 方法 返回 True， 而 它 本 该 返回 


FaLse。 


。 报告 失败 的 测试 ， 以 及 是 哪 一 行 导致 失败 的 。 注 意 ， 如 果 使 用 *nix 系统 或 Mac， 文 件 路 径 有 所 不 同 。 


































































































以 上 就 是 对 Django 测试 的 简单 介绍 。 本 章 开头 说 过 ， 测 试 是 一 门 很 深 的 学 问 ， 涉 及 众多 知识 ， 而 且 对 程序 员 
的 职业 发 展 十 分 重要 。 在 简短 的 一 章 内 容 里 无 法 面面俱到 ， 因 此 我 建议 你 阅读 本 章 提 到 的 资料 和 Django 文 
档 。 


本 章 余下 的 内 容 介绍 Django 提供 的 各 种 测试 工具 。 



























































12.5 测试 工具 























Django 为 编写 测试 提供 了 一 些 便 利 的 工具 。 











12.5.1 测试 客户 端 


测试 客户 端 是 一 个 Python 类 ， 伪装 成 一 个 Web 浏览 避 ， 以 便 通 过 编程 的 方式 测试 Django 应 用 程序 的 视图 和 
交互 。 测 试 客户 端 能 做 的 事情 有 : 









































。 模拟 对 URL 的 GET 和 PosT 请 求 ， 并 监视 响应 ， 这 包括 低层 的 HTTP 信息 (首部 和 状态 码 ) 和 页 面 内 
容 。 
。 跟踪 重 定向 过 程 (如果 有 的 话 ) ， 检 查 这 个 过 程 中 每 一 步 的 URL 和 状态 码 。 


。 测试 指定 的 请 求 由 指定 的 Django 模板 泻 染 ， 而 且 模 板 上 下 文中 包含 特定 的 值 。 
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7/ 
o 


同 











简单 来 说 : 





























意 ， 这 个 测试 客户 端的 目的 不 是 取代 Selenium 或 其 他 操作 浏览 器 的 框架 。Django 的 测试 客户 端 关 注 的 点 不 





。 Django 的 测试 客户 端 用 于 确认 是 否 泻 染 了 正确 的 模板 ， 而 且 为 模板 传人 了 正确 的 上 下 文 数据 。 
。 操作 浏览 器 的 框架 (如 Selenium) 用 于 测试 泻 染 得 到 的 网 页 中 的 内 容 和 行为 ， 尤 其 是 使 用 JavaScript 
实现 的 功能 。 


Django 也 为 那些 框架 提供 了 特别 支持 ， 详 情 参 见 LiveserverTestCase 一 节 。 人 全面 的 测试 组 件 应 该 二 者 结 






























































若 想 查看 详细 的 测试 客户 端 示例 ， 请 访问 Django Project 网 站 。 


12.5.2 内 置 的 测试 用 例 类 


东 














Python 常规 的 

















元 测试 类 扩展 自 unittest.TestCase 类 。Django 为 这 个 基 类 提供 














SimpleTestCase 





扩展 unittest 











.TestCase， 提 供 下 述 基 本 功能 : 








。 保存 和 恢复 Python 提醒 状态 。 
。 添加 一 些 有 用 的 断言 ， 如 : 





。 检查 可 调用 的 对 象 执 出 特定 的 异常 。 

















。 测试 表单 字段 泻 染 和 错误 处 理 。 

。 测试 HTML 响应， 检查 存在 或 没有 指定 的 片段 。 

。 确认 模板 已 经 或 尚未 用 于 生成 指定 的 响应 内 容 。 

。 确认 应 用 做 了 HTTP 重 定向 。 

。 不 严格 测试 两 个 HTML 片段 是 否 相 同 、 不 同 或 有 包含 关系 。 


。 不 严格 测试 两 个 XML 片段 是 否 相同 或 不 同 。 








。 不 严格 测试 两 个 JSON 片段 是 否 相 同 。 











。 使 用 自 定 义 的 设置 运行 测试 。 
。 使 用 测试 客户 端 。 
。 自 定义 测试 -时 间 URL 映射 。 























TransactionTestCase 


Django 的 TestCase 类 (下 文 说 明 ) 利 
而 ， 这 么 做 的 后 果 是 ， 有 些 数 据 库 行 为 在 TestCase 类 中 无 法 测试 。 


了 一 些 扩展 。 









































此 时 ， 应 该 使 
同 ， 而 且 测试 























尺码 能 测试 提交 和 回 深 的 效果 : 








数据 库 事务 提速 每 个 测试 开头 把 数据 库 还 原 为 已 知 状态 的 过 程 。 然 


] TransactionTestCase。 它 的 行为 与 TestCase 一 样 ， 不 过 把 数据 库 还 原 成 已 知 状态 的 方式 不 





。 TransactionTestCase 在 测试 运行 完毕 后 还 原 数 据 库 ， 把 所 有 表 删 除 。TransactionTestCase 可 能 会 调用 


提交 或 


。 而 TestCase 在 测试 完毕 后 不 删除 表 。 它 把 测试 代码 放 在 一 个 数据 库 事务 9 




















回 滚 操作 ， 然 后 在 数据 库 中 监视 效果 。 











PF， 在 测试 的 末尾 回 深 。 这 么 
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做 的 目的 是 确保 把 数据 库 恢 复 到 最 初 状 态 。 





TransactionTestCase 继承 自 SimpleTestCase。 











TestCase 


这 个 类 提供 了 一 些 额 外 的 功能 ， 在 测试 网 站 时 用 得 到 。 把 常规 的 unittest.TestCase 转换 成 Django 的 Test- 
Case 很 容易 : 把 测试 的 基 类 由 unittest.TestCase 改 为 django.test.TestCase 即 可 。 标 准 的 Python 单元 测试 
所 具有 的 功能 仍然 可 用 ， 此 外 还 增加 了 一 些 功能 : 


























。 自动 加 载 固件 。 

。 把 测试 包装 到 两 个 仍 套 的 atomtc 块 中 : 一 个 针对 整个 类 ， 一 个 针对 各 个 测试 。 
。 创建 TestCLient 实例 。 

。 Django 专 有 的 测试 断言 ， 如 用 于 测试 重 定向 和 表单 错误 的 断言 。 












































TestCase 继承 自 TransactionTestCase。 





LiveServerTestCase 


LiveServerTestCase 的 作用 基本 与 TransactionTestCase 相同 ， 不 过 有 个 额外 功能 : 测试 前 在 后 台 启 动 线 上 
Django 服务 器 ， 测 试 后 再 关闭 。 此 时 使 用 的 是 自动 化 测试 客户 端 (Selenium) 而 不 是 Django 的 模拟 客户 端 ， 
因此 可 以 在 浏览 器 中 执行 功能 测试 ， 模 拟 真 实 的 用 户 操作 。 












































12.5.3 测试 用 例 的 功能 


默认 的 测试 客户 端 





*TestCase 类 中 的 每 个 测试 都 能 访问 Django 测试 客户 端 ，setf.ctent。 这 个 客户 端 在 每 个 测试 中 重新 创 到 
因此 不 用 担心 会 带 有 其 他 测试 的 状态 (如 cookie) 。 这 意味 着 ， 不 用 在 每 个 测试 中 实例 化 CHtent: 





| 典 





























import unittest 
from django.test import Client 


class SimpleTest(unittest.TestCase): 
def test details(self): 
client = Client() 
response = client.get('/customer/details/') 
seLf .assertEquaL(response.status_code，200) 


def test_index(self): 
client = Client() 
response = client.get('/customer/index/') 
seLf .assertEquaL(response.status_code，200) 


而 是 通过 self.client 引用 : 


from django.test import TestCase 


class SimpLeTest(TestCase) : 
def test details(self): 
response = self.client.get('/customer/details/') 
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self.assertEqual(response.status_code, 200) 


def test index(self): 
response = self.client.get('/customer/index/') 
self.assertEqual(response.status_code, 200) 


加 载 固件 


如 果 数 据 库 中 没有 数据 ， 对 以 数据 库 为 后 台 的 网 站 来 说 ， 测 试用 例 没有 多 大 用 。Django 自 定义 的 Transac- 
tionTestCase 类 提供 了 一 种 方式 ， 能 简化 把 测试 数据 存 人 数据 库 的 过 程 : 加 载 固件 。 固 件 是 一 系列 数据 ， 
Django 知道 如 何 将 其 导入 数据 库 。 比 如 说 ， 网 站 有 一 些 账户 ， 你 可 以 创建 包含 虚拟 账户 的 固件 ， 在 测试 中 填 


创建 固件 最 简单 的 方式 是 使 用 manage.py dumpdata 命令 。 不 过 前 提 是 数据 库 中 已 经 有 一 些 数据 。 (详情 参见 
dumpdata 命令 的 文档 。) 


创建 好 固件 ， 并 将 其 放 到 INSTALLED_APPS 中 某 个 应 用 的 fixtures 目录 里 之 后 ， 在 django. test.TestCase 的 子 
类 中 设 定 类 属性 fixtures: 

















from django.test import TestCase 
from myapp.models import Animal 


class AnimalTestCase(TestCase): 
fixtures = ['mammals.json', 'birds'] 


def setUp(self): 
# 像 之 前 那样 定义 测试 
call_setup_methods() 


def testFluffyAnimals(self): 
# 一 个 使 用 固件 的 测试 


CaLL_some_test_code() 


加 载 固件 的 过 程 如 下 : 





。 在 各 个 测试 用 例 之 前 ， 也 在 setup() 运行 之 前 ，Django 清理 数据 库 ， 把 数据 库 还 原 成 执行 mgrate 命 
令 之 后 的 状态 。 

。 然后 ， 加 载 所 有 具名 固件 。 这 里 ，Django 会 先 加 载 名 为 nammals 的 JSON 固件 ， 再 加 载 名 为 birds 的 
固件 。 











关于 定义 和 加 载 固件 的 详情 ， 参 阅 Loaddata 命令 的 文档 。 测 试用 例 中 的 每 个 测试 都 会 重复 上 述 清理 和 加 载 过 
程 ， 因 此 可 以 保证 的 是 ， 一 个 测试 的 输出 对 另 一 个 测试 没有 影响 ， 而 且 执行 测试 的 顺序 也 无 关 。 默 认 情 况 
下 ， 固 件 只 加 载 到 defautt 数据 库 中 。 如 果 使 用 多 个 数据 库 ， 而 且 设 定 了 multi_db=True， 固 件 会 加 载 到 所 有 
数据 库 中 。 





覆盖 设置 


下 述 函数 仅 用 于 在 测试 中 临时 修改 设置 。 别 直接 处 理 django.conf.settings， 因 为 修改 之 后 无 
法 还 原 成 原来 的 值 。 
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settings() 





测试 中 经 常 需要 临时 修改 设置 ， 然 后 在 测试 完毕 后 恢复 原 值 。 为 此 ，Django 提供 了 一 个 标准 的 Python 上 下 
文 管理 器 (参见 PEP 343) ， 名 为 settings()。 用 法 如 下 : 




















from django.test import TestCase 
class LoginTestCase(TestCase): 
def test login(self): 


# 首先 检查 默认 的 行为 
response = self.client.get('/sekrit/') 
self.assertRedirects(response, '/accounts/login/?next=/sekrit/') 


# 然后 履 盖 LOGIN_URL 设置 
with seLf .settings(LOGIN_URL= ' /other/Login/ ' ): 
response = self.client.get('/sekrit/') 
seLf .assertRedirects(response， '/other/login/?next=/sekrit/') 


这 个 示例 在 with 块 中 覆盖 LOGIN_URL 设置 ， 然 后 恢复 原 值 。 








modify_settings() 








重新 定义 值 为 列表 的 设置 很 不 方便 。 实 际 使 用 中 ， 添 加 或 删除 元 素 往 往 就 行 了 。modify_settings() 上 下 文 管 
理 器 能 简化 这 个 过 程 : 











from django.test import TestCase 


class MiddlewareTestCase(TestCase): 


def test_cache _ middleware(self): 
with self.modify_settings(MIDDLEWARE_CLASSES={ 
"append' : 'django.middleware.cache.FetchFromCacheMiddleware', 
"prepend' : 'django.middleware.cache.UpdateCacheMiddleware', 
'remove': [ 
'django.contrib.sessions.middleware.SessionMiddleware', 
'django.contrib.auth.middleware.AuthenticationMiddleware', 
'django.contrib.messages.middleware.MessageMiddleware', 
中 
]) : 
response = self.client.get('/') 
i 





























每 次 操作 可 以 提供 一 组 值 或 一 个 字符 串 。 如 果 列 表 中 已 有 提供 的 值 ，append 和 prepend 无 效果 ， 如 果 列 表 中 
没有 提供 的 值 ，remove 也 没 效 果 。 








override_settings() 




















如 果 想 在 测试 方法 中 覆盖 设置 ， 使 用 Django 提供 的 override_settings() 装饰 器 (参见 PEP 318) 。 用 法 如 
下 : 




















from django.test import TestCase, override settings 
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class LoginTestCase(TestCase): 


Qoverride_settings(LOGIN_URL=' /other/Logtn/ ') 

def test_login(self): 
response = self.client.get('/sekrit/') 
self.assertRedirects(response, '/other/login/?next=/sekrit/') 


这 个 装饰 器 还 可 运用 到 测试 用 例 类 上 : 


from django.test import TestCase, override settings 


@override_settings(LOGIN_URL="'/other/Llogin/') 
class LoginTestCase(TestCase): 


def test login(self): 
response = self.client.get('/sekrit/') 
self.assertRedirects(response, '/other/login/?next=/sekrit/') 


modify_settings() 
同样 ，Django 还 提供 了 modify_settings() 装饰 器 : 


from django.test import TestCase，modify_settings 
class MiddlewareTestCase(TestCase): 


@modify_settings(MIDDLEWARE_CLASSES={ 
'append': 'django.middleware.cache.FetchFromCacheMiddleware', 
'prepend': 'django.middleware.cache.UpdateCacheMiddleware', 
yy, 
def test cache middleware(self): 
response = self.client.get('/') 
i 


这 个 装饰 器 也 可 以 运用 到 测试 用 例 类 上 : 
from django.test import TestCase, modify_settings 


@modify_settings(MIDDLEWARE_ CLASSES={ 
'append': 'django.middleware.cache.FetchFromCacheMiddleware', 
'prepend': 'django.middleware.cache.UpdateCacheMiddleware', 
}) 


class MiddlewareTestCase(TestCase): 


def test cache middleware(self): 
response = self.client.get('/') 
-J 














覆盖 设置 时 要 记得 处 理 使 用 缓存 或 类 似 功 能 的 情况 ， 因 为 此 时 即使 修改 设置 ， 状 态 依然 不 变 。Django 提供 了 
django. test.signals.setting_changed 信和 号， 你 可 以 注册 回调 ， 在 状态 改变 时 清理 或 还 原状 态 。 
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断 


了 

































































































































































Python 中 常规 的 unittest.TestCase 类 实现 了 assertTrue() 和 assertEquaL() 等 断言 方法 ，Django 自 定 义 的 
TestCase 类 提供 了 一 些 对 测试 Web 应 用 有 用 的 断言 方法 : 

。 assertRaisesMessage: 断言 执行 的 可 调用 对 象 抛 出 了 异常 ， 而 且 消 息 为 expected_message。 

。 assertFieldoutput: 断言 表单 字段 的 行为 在 多 种 输入 下 是 正确 的 。 

。 assertfornError， 断言 泻 染 表 单 时 革 个 字段 抽出 指定 列表 中 的 错误 。 

。 assertFormsetError: 盯 言 泻 染 formset 时 抛 出 指定 列表 中 的 错误 。 

。 assertContains: 断言 Response 实例 的 状态 码 为 status_code， 而 且 text 出 现在 啊 应 内 容 中 。 

。 assertNotContains: 汤 言 Response 实例 的 状态 码 为 status_code， 但 是 text 未 出 现在 响应 内 容 中 。 


assertTemplateUsed: 断言 使 用 指定 名 称 的 模板 泻 染 响 


index.htmL ' 。 




















assertTemplateNotUsed: 汤 言 未 使 





据 ) ， 而 且 收 到 的 最 终 页 和 











assertHTMLEqual: 断言 字 


























忽略 HTML 标签 前 后 的 空白 。 





起 始 标 签 隐 式 关闭 ， 


不 管 是 何 种 空白 ， 都 认为 相同 。 
侈 如 外 层 标 签 关闭 ， 或 者 HTML 文档 结束 。 
空 标签 与 自 关 闭 版 本 相同 。 





HTML 元 素 属性 的 顺 
。 没 























9 值 的 属性 与 名 称 和 值 一 样 的 属性 相同 ( 








指定 名 称 的 模板 泻 染 响应 。 


assertRedirects: 断言 响应 是 状态 码 为 status_code 的 习 
的 状态 码 是 target_status_code。 





详 见 示例 ) 。 


Y。 模 板 的 名 称 是 一 个 字符 串 ， 例 如 'admin/ 


定向 ， 重 定向 到 expected_url (包含 GET 数 


符 串 html1 和 html2 相同 。 基 于 HTML 语义 比较 。 比 较 时 会 考虑 下 述 情况 : 


assertHTMLNotEquaL:， 上 断言 字符 串 htmtl1l 和 html2 不 同 。 基 于 HTML 语义 比较 。 详 情 参 见 assertHTM- 


LEqual()。 





assertXMLEquaL:， 上 断言 字符 串 xmL1 和 xmL2 相同 。 基 于 XML 语义 比较 。 与 assertHTMLEqual() 类 似 ， 


比较 的 是 解析 后 的 内 容 ， 因 

















assertXMLNotEqual: 岂 言 字符 


qual()。 


assertInHTML: 断言 HTML 片段 needle 包含 在 haystack 中 。 


assertJSONEqual: 汤 言 JSON 片段 raw 和 expected_data 相 


叶 





此 只 考虑 语义 区 别 ， 而 不 是 句法 
串 xmll 和 xmtL2 不 同 。 基 于 XML 语义 比较 。 详 情 参 见 assertXMLE- 











同 。 


区 别 。 





assertJSONNotEqual: 断言 JSON 片段 raw 和 expected_data 不 同 。 
assertQuerysetEqual: 上 断言 查询 集合 qs 返回 values 中 指定 的 一 组 值 。 使 用 transform 函数 比较 qs 和 














values 的 内 容 。 默 认 情 况 下 ， 这 意味 着 比较 的 是 每 














个 值 的 字符 串 表 示 形 式 (repr()) 。 


assertNumQueries: 断言 调用 func 时 传人 *args 和 **kwargs， 执 行 的 数据 库 查 询 次 数 为 num。 


12.5.4 电子 邮件 服务 


四 
2 


如 








Django 视 











区 | 

















使 用 Django 的 电子 邮件 功能 发 送 











电子 邮件 ， 你 可 能 不 想 每 次 运行 那个 视 





区 | 














的 测试 时 都 发 








样 能 全 方位 测试 由 


送 电子 邮件 。 鉴 于 出 
从 





上 ，Django 的 测试 运行 程序 








自动 把 

















Django 发 出 的 由 





Pp 伯 




















F 重 定向 到 一 个 模拟 的 发 件 箱 中 。 这 


F 发 送 ， 从 发 送 的 数量 到 每 封 邮 件 的 内 容 ， 而 不 用 真 的 发 送 邮 件 。 测 试 运行 


程序 在 背 























所 
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做 的 是 ， 把 常规 的 电子 邮件 后 端 替 换 成 测试 后 端 。 〈 别 担心 ， 这 对 Django 外 部 的 邮件 发 送 程序 没有 任何 影 
响 ， 例 如 设备 中 的 邮件 服务 器 。) 





运行 测试 时 ， 发 出 的 电子 邮件 保存 在 django.core.mail.outbox 中 。 这 是 一 个 由 EmailMessage 实例 构成 的 列 
表 。outbox 是 个 特殊 的 属性 ， 仅 当 使 用 Locmen 电子 邮件 后 端 时 才 创 建 。 它 不 是 django.core.mail 模块 的 常 
规 组 成 部 分 ， 无 法 直接 导入 。 下 述 代码 展示 如 何 正 确 地 访问 这 个 属性 。 下 述 示 例 测试 检查 djan- 
go.core.mail.outbox 的 长 度 和 内 容 : 









































from django.core import mail 
from django.test import TestCase 


class EmailTest(TestCase): 
def test send email(self): 
# 发 送 邮 件 
mail.send_mail('Subject here', 'Here is the message.', 
'from@example.com', ['to@example.com'], 
fail_silently=False) 


# 断言 发 出 了 一 封 邮 件 
self.assertEqual(len(mail.outbox), 1) 


# 验证 第 一 封 邮件 的 主题 是 正确 的 
self.assertEqual(mail.outbox[0].subject, 'Subject here') 


如 前 所 述 ，*TestCase 中 的 每 个 测试 运行 前 都 会 清空 测试 发 件 箱 。 如 果 想 手动 清空 ， 把 mail.outbox 设 为 一 个 
空 列表 : 


from django.core import mail 


# 清空 测试 发 件 箱 
mail.outbox = [] 


管理 命令 可 以 使 用 call_command() 函数 测试 。 输 出 可 以 重 定 向 到 一 个 StringI0 实例 中 








from django.core.management import call_command 
from django.test import TestCase 
from django.utils.six import StringIO 


class ClosepollTest(TestCase): 
def test_command_output(self): 
out = StringI0() 
call_command('closepoll', stdout=out) 
self.assertIn('Expected output', out.getvalue()) 


12.5.6 跳 过 测试 











如 果 事 先知 道 特定 的 情况 下 测试 将 失败 ， 可 以 使 用 unittest 库 提供 的 @skipIf 和 @skipunless 装饰 器 跳 过 测 
试 。 假 如 测试 需要 特定 的 可 选 库 才 能 通过 ， 可 以 使 用 @skipIf 装饰 测试 用 例 。 然 后 ， 测 试 运行 程序 会 报告 测 
试 未 执行 ， 并 指明 原因 ， 而 不 是 让 测试 失败 ， 或 者 将 其 忽略 。 
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12.6 测试 数据 库 

















需要 数据 库 的 测试 〈 即 模型 测试 ) 不 会 使 用 生产 数据 库 ，Django 会 为 测试 单独 创建 空 数据 库 。 不 管 测试 通过 
还 是 失败 ， 测 试 数据 库 都 在 全 部 测试 执行 完毕 后 销毁 。 如 果 不 想 销毁 测试 数据 库 ， 运 行 test 命令 时 指定 -- 
keepdb 旗 标 。 这 样 ， 在 两 次 运行 测试 之 间 测 试 数据 库 会 留存 下 来 。 



































如 果 测 斌 数据库 不 存在 ， 首 先 新 建 。 为 了 保证 模式 最 新 ， 还 会 运行 迁移 。 默 认 情 况 下 ,测试 数据 库 的 名 称 是 
在 DATABASES 设置 中 的 NAME 选项 前 加 test_。 如 果 使 用 SQLite 数据 库 引 警 ， 测 试 默认 使 用 内 存 中 的 数据 库 
( 即 ， 数 据 库 在 内 存 中 创建 ， 完 全 不 用 文件 系统 ) 。 


如 果 想 使 用 其 他 数据 库 名 称 ， 在 TEST 设置 中 为 DATABASES 设置 列 出 的 各 个 数据 库 指定 NAME 选项 。 使 用 Post- 
greSQL 时 ，USER 还 要 有 内 置 postgres 数据 库 的 读 权 限 。 对 同一 个 数据 库 来 说 ， 测 试 运行 程序 始终 使 用 设置 
文件 中 的 数据 库 设 置 : ENGINE、USER、H0ST， 等 等 。 测 试 数据 库 由 USER 指定 的 用 户 创 建 ， 因 此 要 确保 指定 的 
用 户 有 足够 的 权限 在 系统 中 新 建 数 据 库 。 



























































































































































12.7 使 用 其 他 测试 框架 


HH 











显然 ，unittest 不 是 唯一 的 Python 测试 框架 。 虽 然 Django 不 直接 支持 其 他 测试 框架 ,但 是 却 为 调用 其 他 框 
架 编写 的 测试 提供 了 方式 ， 让 Django 认为 那 就 是 普通 的 Django 测试 。 









































执行 ./manage.py test 命令 时 ，Django 根据 TEST_RUNNER 设置 决定 接 下 来 做 什么 。TEST_RUNNER 默认 指向 
django.test.runner.DiscoverRunner。 这 个 类 定义 Django 默认 的 测试 行为 ， 包 括 : 








1， 执 行 全 局 的 测试 前 准备 工作 。 














2， 在 当前 目录 中 查找 名 称 匹 配 test* ,py 模式 的 测试 文件 。 
3， 创 建 测试 数据 库 。 

4. 运行 了 迁移， 把 模型 和 初始 数据 填充 到 测试 数据 库 中 。 
5， 运 行 找到 的 测试 。 

6， 销 毁 测试 数据 库 。 

7， 执 行 全 局 的 测试 后 清理 工作 。 


























如 果 你 自己 定义 了 测试 运行 程序 类 ， 而 且 把 TEST_RUNNER 指向 它 ， 每 次 执行 ./manage.py test 命令 时 ，Djan- 
go 都 会 使 用 那个 测试 运行 程序 。 


如 此 以 来 便 可 以 使 用 任何 Python 测试 框架 ,或 者 调整 Django 执行 测试 的 过 程 ， 满 足 特定 的 需求 。 











关于 这 个 话题 的 详细 说 明 ， 参 见 Django Project 网 站 。 


12.8 接 下 来 











现在 你 知道 如 何 为 自己 的 Django 项 目 编写 测试 了 ， 下 面 我 们 换个 重要 话题 ， 讨 论 如 何 把 项 目 变 成 真正 的 线 上 
网 站 ， 即 把 Django 项 目 部 署 到 Web 服务 器 上 。 
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本 章 介绍 构建 Django 应 用 程序 的 最 后 一 个 重要 步骤: 把 应 用 程序 部 署 到 生产 服务 器 。 














如 果 你 一 直 跟 着 书 中 的 示例 做 ， 那 就 用 过 runserver 命令 了 。 这 个 命令 简化 了 相关 操作 ， 不 用 你 费心 搭建 
Web 服务 器 。 但 是 ，runserver 只 适合 在 本 地 设备 中 做 开发 ， 不 能 在 公开 Web 中 使 用 。 















































若 想 部 署 Django 应 用 程序 ， 要 使 用 工业 级 Web 服务 器 ， 例 如 Apache。 本 章 将 说 明 具体 怎么 做 。 不 过 ， 首 先 














13.1 为 上 线 做 好 准备 


13.1.1 部 署 点 检 表 


互联 网 危机 四 伏 。 部 署 Django 





要 告诉 你 上 线 之 前 需要 在 代码 基 中 做 的 事情 。 








项 目 之 前 ， 应 该 花 点 时 间 审 查 设 置 ， 考 虑 安全 、 性 能 和 运 维 。 




















Django 包含 很 多 安全 措施 ， 有 些 是 内 置 的 ， 而 且 始 终 肩 用， 有些 则 是 可 选 的 ， 因 为 并 非 始 终 适 用 ， 或 者 对 开 
发 不 便 。 例 如 ， 强 制 使 用 HITPS 可 能 不 适合 所 有 网 站 ， 在 本 地 开发 中 也 没有 意义 。 


性 能 优化 也 是 为 了 便利 而 有 所 牺牲 的 一 方面 。 例 如 ， 缓 存 对 生产 环境 很 有 用 ， 但 是 在 本 地 开发 中 就 没 多 大 用 
处 。 错 误 报告 需求 也 有 诸多 不 同情 况 。 接 下 来 介绍 的 点 检 表 涉及 以 下 几 方面 的 设置 : 















































。 必须 正确 设置 ， 以 便 提 供 预期 的 安全 级 别 














。 在 各 个 环境 中 本 该 不 同 
。 启用 可 选 的 安全 措施 
。 启用 性 能 优化 


。 提供 错误 报告 






































这 些 设置 中 很 多 是 敏感 的 ， 应 该 视 作 机 密 。 如 果 想 发 布 项 目的 源码 ， 常 见 的 做 法 是 公开 适合 开发 使 用 的 设 
置 ， 而 在 生产 环境 中 使 用 隐私 的 设置 模块 。 下 面 所 述 的 检查 项 目 中 ， 有 些 可 以 在 check 命令 中 指定 --deploy 
选项 自动 检查 。 一 定 要 像 - -deptoy 选项 的 文档 中 所 说 的 那样 使 用 这 个 命令 检查 生产 环境 的 设置 文件 。 





























13.2 关键 设置 


13.2.1 SECRET_KEY 


密 钥 必须 是 一 长 串 随 机 值 ， 而 ] 

















日 必须 保密 。 











千 万 不 能 在 别处 使 用 生产 环境 的 密 钥 ， 而 且 不 能 提交 到 源码 控制 系统 中 。 这 么 做 是 为 了 降低 攻击 者 盗 取 密 钥 
的 机 会 。 别 在 设置 模块 中 硬 编码 密 钥 ， 应 该 考虑 从 环境 变量 中 加 载 : 














import os 
SECRET_KEY = os.environ[ 


或 者 从 文件 中 加 载 : 

















'SECRET_KEY'] 
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with open('/etc/secret key.txt') as f: 
SECRET_KEY = f.read().strip() 


13.2.2 DEBUG 
一 定 不 能 在 生产 环境 启用 调试 模式 。 


我 们 在 第 1 章 创建 项 目 时 ，django-admin startproject 命令 创建 的 settings.py 文件 把 DEBUG 设 为 True。 
Django 的 很 多 内 部 组 件 检查 这 个 设置 ， 如 果 启 用 了 调试 模式 ,行为 有 所 不 同 。 



































假如 把 DEBUG 设 为 True 了 ， 那 么 : 


。 所 有 数据 库 查询 以 django.db.connection.queries 对 象 的 形式 存储 在 内 存 中 。 可 以 想象 ， 这 样 很 耗 内 
存 ! 

。 404 错误 使 用 Django 特殊 的 404 页 面 泻 染 (参见 第 3 章 ) ， 而 不 是 返回 404 响应 。 那 个 页 面 可 能 包含 
敏感 信息 ， 因 此 不 应 该 公开 在 互联 网 中 显示 。 

。 Django 应 用 程序 中 任何 未 捕获 的 异常 (从 基本 的 Python 句法 错误 、 数 据 库 错误 ， 到 模板 句法 错误 ) 
都 使 用 Django 精美 的 错误 页 面 泻 染 。 你 可 能 见 过 这 个 页 面 ， 而 且 很 喜欢 。 这 个 页 面包 含 的 敏感 信息 比 
404 页 面 还 多 ， 决 不 能 公开 显示 。 








































































































简单 来 说 ， 把 DEBUG 设 为 True 是 告诉 Django， 只 有 信任 的 开发 者 在 使 用 网 站 。 互 联网 鱼龙混杂 ， 因 此 准备 部 
署 应 用 程序 时 ， 首 先 应 该 把 DEBUG 设 为 Fatse。 


















































13.3 各 环境 专用 的 设置 


13.3.1 ALLOWED_HOSTS 

















设 定 DEBUG = False 之 后 ， 如 果 不 为 ALLONWED_H0STS 设 定 合适 的 值 ，Django 根本 无 法 运转 。 这 个 设置 的 作用 
是 防范 某 些 CSRF 攻击 ， 因 此 必须 设 定 。 如 果 使 用 泛 域名 ,必须 自行 验证 HTTP Host 首部， 或 者 确保 没有 这 
方面 的 漏洞 。 









































13.3.2 缓存 




















如 果 使 用 缓存 ， 开 发 环境 和 生产 环境 使 用 的 连接 参数 可 能 不 同 。 缓 存 服 务 器 往往 不 严格 验证 身份 ， 因 此 要 
保 只 接受 来 自 应 用 服务 器 的 连接 。 如 果 使 用 Memcached， 请 考虑 缓存 会 话 ， 以 提升 性 能 。 


















































13.3.3 数据 库 





数据 库 连 接 参 数 在 开发 环境 和 生产 环境 中 可 能 不 同 。 数 据 库 密码 是 敏感 信息 ， 应 该 像 SECRET_KEY 那样 保护 起 
来 。 为 了 最 大 限度 的 增强 安全 ， 确 保 数 据 库 服务 器 只 接受 来 自 应 用 服务 器 的 连接 。 如 果 没 做 数据 库 备 份 ， 现 
在 就 做 吧 ! 





















































13.3.4 EMAIL_BACKEND 和 相关 的 设置 











娄 


默认 情况 下 ，Django 发 送 的 邮件 使 用 的 发 件 人 是 webmaster@localhost 和 root@localhost， 但 是 有 些 邮 件 提 供 
商 拒 收 这 两 个 地 址 发 送 的 邮件 。 如 果 想 使 用 其 他 发 件 地 址 ， 修 改 DEFAULT_FROM_EMAIL 和 SERVER_EMAIL 设置 。 


果 你 的 网 站 要 发 送 电 子 邮件 ， 下 述 设置 要 正确 设置 。 








FP == 













































































192 -第 13 章 部 署 Django 应 用 程序 


13.3.5 STATIC_ROOT 和 STATIC_URL 











em| 











中 那个 目录 中 的 静态 文件 。 


= 


13.3.6 MEDIA_ROOT 和 MEDIA_URL 











媒体 文件 由 用 户 上 传 ， 是 不 能 信任 的 ! Web 服务 器 一 定 不 能 去 解释 



































F 发 服务 器 自动 伺服 静态 文件 。 但 是 在 生产 环境 中 必须 定义 STATIC_R0OT 目录 ，collectstatic 命令 会 自动 复 

















j 户 上 传 的 媒体 文件 。 例 如 ，Web 服务 器 


不 应 该 执行 用 户 上 传 的 .php 文件 。 现 在 是 检查 媒体 文件 备份 策略 的 好 时 机 。 


13.4 HTTPS 


允许 用 户 登录 的 网 站 都 应 该 强制 全 站 使 用 HITPS ， 以 防 明 文 传输 访问 令 牌 。 在 Django 中 ， 访 问 令 牌 包括 用 


了 什么 。) 








户 名 、 密 码 、 会 话 cookie 和 密码 重 设 令 牌 。 


保护 用 户 账 户 或 管理 后 台 等 敏感 区 域 还 不 够 ， 
























































(如 果 通 过 电子 邮件 发 送 密码 重 设 令 牌 ， 为 了 保护 令 牌 ， 你 做 不 


因为 HITP 和 HTTPS 用 的 是 相同 的 会 话 cookie。Web 服务 器 





必须 把 HTTP 流量 重 定向 到 HTTPS， 只 通过 HTTPS 请 求 Django。 设 置 好 HTTPS 后 ， 启 用 下 述 设置 。 


13.4.1 CSRF_COOKIE_SECURE 


设 为 True， 以 防 不 小 心 通 过 HTTP 传输 CSRF cookie。 


13.4.2 SESSION_COOKIE_SECURE 


设 为 True， 以 防 不 小 心 通过 HTTP 传输 会 话 cookie。 


13.5 性 能 优化 





























设 定 DEBUG = False 后 ， 禁 用 了 几 个 只 在 开发 中 有 用 的 功能 。 此 外 ， 可 以 调整 下 述 几 个 设置 。 








13.5.1 CONN_MAX_AGE 





如 果 处 理 请 求 时 连接 数据 库 所 用 的 时 间 占 据 相 当 一 部 分 ， 可 以 启 
































时 。 在 网 络 性 能 受 限 的 虚拟 主机 中 这 么 做 效果 明显 。 


13.5.2 TEMPLATES 





缓存 模板 加 载 右 通常 能 极 大 地 提升 性 能 ， 





13.6 错误 报告 





持久 数据 库 连 接 ， 有 效 减 少 这 一 部 分 的 耗 











因为 无 需 每 次 泻 染 都 编译 模板 。 详 情 参 见 模板 加 载 器 的 文档 。 

















把 代码 推送 到 生产 环境 后 ， 我 们 都 希望 能 顺利 运行 ， 但 是 意外 错误 是 不 可 避免 的 。 幸 好 ，Django 能 捕获 错 











误 ， 并 以 合适 的 方式 通知 你 。 








13.6.1 日 志 














网 站 上 线 之 前 要 检查 日 志 配 置 ， 而 且 要 下 








保 在 有 一 定 流量 之 后 能 按 预 


























期 工作 。 
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13.6.2 ADMINS 和 MANAGERS 


二 


出 现 500 错误 时 ， 会 通过 邮件 通知 ADMINS。 出 现 404 错误 时 ， 会 通过 邮件 通知 MANAGERS。IGNOR- 
ABLE_404_URLS 可 以 防止 误 报 。 


通过 电子 邮件 报告 错误 不 太 便 利 。 在 收 件 箱 没 被 报告 淹没 之 前 考虑 使 用 错误 监控 系统 吧 ， 例 如 Sentry。Sentry 


通过 
还 能 聚合 日 志 。 



























































13.6.3 自 定义 默认 的 错误 视图 

















Django 为 几 个 HTTP 错误 码 提供 了 默认 的 视图 和 模板 。 你 可 以 在 根 模板 目录 中 创建 这 几 个 模板 覆盖 默认 的 模 
板 : 404.htmL、500.htmL、403.htmL 和 400.htmL。999% 的 Web 应 用 使 用 默认 视图 即 可 ， 但 是 如 果 你 想 自 定 
义 ， 请 看 这 里 的 说 明 。 那 份 文档 还 详细 说 明了 下 述 默认 模板 : 






































。 http_not_found_view 
。 http_internal_server_error_view 
。 http_forbidden view 


。 http_bad_request_ view 


13.7 使 用 虚拟 环境 





如 果 你 把 项 目的 Python 依赖 安装 到 一 个 虚拟 环境 中 ， 还 要 把 虚拟 环境 中 的 site-packages 目录 添加 到 Python 
路 径 中 。 为 此 ， 要 把 额外 的 路 径 添加 到 WSsGIPythonPath 指令 中 ， 在 Unix 类 系统 中 使 用 冒号 (:) 分 隔 多 个 路 
径 ， 在 Windows 中 则 使 用 分 号 (;) 。 如 果 目 录 的 路 径 中 包含 空白 字符 ， 整 个 路 径 要 放 在 引号 内 。 


























WSGIPythonpath /path/to/mysite.com:/path/to/your/venv/lib/python3.X/site-packages 











要 提供 虚拟 环境 的 正确 路 径 ， 并 把 python3.X 替换 成 正确 的 Python 版 本 (如 python3.4) 。 





13.8 在 生产 环境 中 使 用 不 同 的 设置 





目前 ， 书 中 的 示例 只 使 用 一 个 设置 文件 ， 即 django-admin startproject 命令 生成 的 settings.py。 不 过 ， 准 
备 部 署 时 ， 你 可 能 会 发 现 需要 使 用 多 个 设置 文件 ， 把 开发 环境 和 生产 环境 区 分 开 。 (例如 ， 想 在 本 地 测试 代 
码 时 ， 你 可 不 想 每 次 都 把 DEBUG 设置 由 False 改 成 True。) Django 允许 使 用 多 个 设置 文件 ， 大 大 简化 了 这 一 
需求 的 实现 。 如 果 想 把 生产 环境 和 开发 环境 的 设置 分 别 保存 在 不 同 的 文件 中 ， 可 以 使 用 下 述 三 种 方法 中 的 一 
种 : 



























































。 使 用 两 个 完全 独立 的 设置 文件 。 

。 创建 一 个 基 设 置 文件 (比如 说 针对 开发 环境 ) ， 另 外 创建 一 个 文件 (比如 说 针对 生产 环境 ) ， 导 入 基 
设置 ， 在 里 面 定 义 需 要 覆盖 的 设置 。 

。 只 使 用 一 个 设置 文件 ， 通 过 Python 逻辑 根据 上 下 文 修改 设置 。 


















































下 面 一 一 说 明 。 首 先 ， 最 简单 的 方法 是 定义 两 个 独立 的 设置 文件 。 如 果 你 一 直 跟 着 我 做 ， 现 在 已 经 有 了 set- 
tings.py 文件 。 那 么 ， 我 们 只 需 复制 一 份 ， 将 其 命名 为 settings_production.py。 (文件 名 是 我 随便 起 的 ， 
你 可 以 随便 命名 。) 然后 ， 在 这 个 新 文件 中 修改 DEBUG 等 设置 。 第 二 种 方法 类 似 ， 不 过 去 除了 宛 余 。 我 们 不 
再 创建 两 个 内 容 差 不 多 的 设置 文件 ， 而 是 以 一 个 为 基础 ， 将 其 导入 男 一 个 文件 。 例 如 : 






































# settings.py 
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DEBUG = True 
TEMPLATE_DEBUG = DEBUG 


DATABASE_ENGINE = 'postgresql_psycopg2" 
DATABASE_NAME = 'devdb' 

DATABASE_USER = "" 

DATABASE_PASSWORD = "" 

DATABASE_PORT = "" 


# settings_production.py 


from settings import * 


DEBUG = TEMPLATE_ DEBUG = False 
DATABASE_NAME = 'production’ 
DATABASE_USER = 'app' 
DATABASE_PASSWORD = "Letmein' 





这 里 ，settings_production.py 从 settings.py 中 导入 全 部 设置 ， 然 后 针对 生产 环境 重新 定义 一 些 设置 。 例 


如 ， 


是 只 


最 后 ， 





这 里 ， 我 们 从 Python 标准 库 中 导入 socket 模块 ， 
断代 码 是 否 运行 在 生产 服务 器 中 。 这 是 
文件 ， 可 以 执行 任何 逻辑 ， 等 等 。 注 意 ， 如 果 采 


抛 上 


重新 定义 DEBUG 等 基本 设置 。) 


























我 们 把 DEBUG 设 成 了 False， 还 修改 了 数据 库 连 接 参 数 。 (后 者 是 为 了 说 明 可 以 重新 定义 任何 设置 ， 而 不 
能 








取 
环境 的 一 种 方式 是 检查 当前 主机 名 。 例 如 : 


# settings.py 

import socket 

if socket.gethostname() == 'my-Laptop ': 
DEBUG = TEMPLATE DEBUG = True 

else: 


DEBUG = TEMPLATE_DEBUG = False 


i 

















区 分 不 同 环境 的 设置 最 简洁 的 方法 是 只 使 用 








的 关键 是 ， 





个 文件 ， 但 是 根据 条 件 分 别 为 各 个 环境 定义 设置 。 区 分 








使 用 它 检查 当前 系统 的 主机 名 。 通 过 检查 主机 名 ， 可 以 判 
设置 文件 中 的 内 容 就 是 普通 的 Python 代码 ， 可 以 导入 其 他 

















settings.py 文件 的 名 称 可 以 随意 起 ， 例 如 settings_dev.py、settings/dev.py 或 foobar.py，Django 并 不 在 


2 
ES 
/区 、)》 





设置 。 这 是 


上 异常 ，Django 有 可 能 骨 溃 。 











只 要 告诉 它 你 使 用 的 是 哪个 就 行 。 





























j 这 种 方法 ， 设 置 文件 中 的 Python 代码 是 可 以 纠 错 的 。 如 果 








但 是 ， 如 果真 的 重 命 名 了 django-admin startproject 命令 生成 的 settings.py，manage.py 会 报错 ， 说 找 不 到 
因为 ，manage.py 尝试 导 人 一 个 名 为 settings 的 模块 。 这 个 问题 的 解决 方法 是 ， 修 改 nanage.py 














文件 ， 把 settings 改 为 新 的 模块 名 ， 或 者 用 django-admin 代替 manage.py。 如 果 采 用 后 一 种 方法 ， 要 设 定 
DJANGO_SETTINGS_MODULE 环境 变量 ， 指 向 设置 文件 的 Python 路 径 (例如 'mysite.settings') 。 
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13.9 把 Django 应 用 程序 部 署 到 生产 服务 器 


别 给 自己 找 麻 烦 


如 果 你 真 想 部 署 一 个 线 上 网 站 ， 明 智 的 做 法 只 有 一 个 : 找 一 个 明确 支持 Django 的 主机 。 这 样 
的 主机 不 仅 自 带 媒体 服务 器 (通常 是 Nginx) ， 还 会 为 你 做 好 一 些 设置 ， 比 如 配置 好 Apache， 
以 及 定期 重启 Python 进程 的 定时 任务 (cron job， 避 免 网 站 停机 ) 。 有 些 优秀 主机 可 能 还 会 提 
供 菜 种 形式 的 “一 键 "部 署 功能 。 


真 的 ， 别 给 自己 找 麻 烦 ， 找 个 支持 Django 的 主机 吧 ， 一 个 月 用 不 了 几 块 钱 。 











13.10 使 用 Apache 和 mod_wsgi 部 署 Django 应 用 程序 


经 证 明 ， 使 用 Apache 和 mod_wsgi 部 署 Django 应 用 程序 是 有 效 的 方式 。mod_wsgi 是 Apache 的 一 个 模块 ， 能 
存 贮 任何 Python WSGI 应 用 程序 ， 包 括 Django。 任 何 支 持 mod_wsgi 的 Apache 版 本 都 可 以 。mod_wsgi 的 官方 
文档 很 全 面 ， 详 述 了 mod_wsgi 的 方方面面 。 或 许 ， 首 先 应 该 阅读 安装 和 配置 文档 。 











13.10.1 基本 配置 


安装 并 激活 mod_wsgi 之 后 ， 编 辑 Apache 服务 器 的 httpd.conf 文件 ， 添 加 下 述 内 容 。 注 意 ， 如 果 使 用 的 
Apache 版 本 低 于 2.4， 把 Require all granted 替换 成 ALLow from all， 并 在 前 面 一 行 添 加 Order deny,al- 
Low。 















































WSGIScriptALias / /path/to/mysite.com/mysite/wsgi.py 
WSGIPythonPath /path/to/mysite.com 


<Directory /path/to/mysite.com/mysite> 
<Files wsgi.py> 

Require all granted 

</Files> 

</Directory> 








WsGIScriptAlias 那 行 里 的 第 一 部 分 是 伺服 应 用 程序 的 基 URL (/ 表示 根 URL) ， 第 二 部 分 是 WSGI 文件 在 
系统 中 的 位 置 (参见 下 文 ) ， 这 个 文件 通常 在 项 目 包 中 (这 里 的 mysite) 。 这 一 行 告诉 Apache， 使 用 那个 文 
件 中 定义 的 WSGI 应 用 程序 在 指定 的 URL 下 伺服 请 求 。 





























WSGIPythonPath 那 行 确保 项 目 包 在 Python 路 径 中 ， 可 以 导入 。 也 就 是 说 ， 让 import mysite 可 用 。<Directo- 
ry> 部 分 确保 Apache 能 访问 wsgi.py 文件 。 


接 下 来 要 确保 wsgi.py 文件 中 有 一 个 WSGI 应 用 程序 对 象 。 从 Django 1.4 开始 ，startproject 命令 会 自动 创 
建 ， 如 果 使 用 旧版 ， 需 要 自行 创建 。 


这 个 文件 中 默认 的 内 容 ， 以 及 可 以 添加 的 其 他 内 容 参见 这 篇 文档 。 
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如 果 在 一 个 mod_wsgi 进程 中 运行 多 个 Django 网 站 ， 所 有 网 站 都 使 用 第 一 个 运行 的 设置 。 如 果 
不 想 这 样 ， 可 以 把 wsgi.py 文件 中 的 


os.environ.setdefault("DJANGO_SETTINGS MODULE", "{{ project name }}.settings") 
改 成 : 
os.environ["DJANGO_SETTINGS_MODULE"] = "{{ project_ name }}.settings" 


或 者 使 用 mod_wsgi 守护 进程 模式 ， 并 确保 各 个 网 站 在 各 自 的 守护 进程 中 运行 。 





13.10.2 使 用 mod_wsgi 的 守护 进程 模式 


推荐 使 用 守护 进程 模式 运行 mod_wsgi (Windows 除外 ) 。 为 了 创建 所 需 的 守护 进程 组 ， 并 委托 它 运 行 Django 
实例 ， 要 添加 合适 的 WSGIDaemonProcess 和 NSGIProcessGroup 指 今 。 

















除 此 之 外 ， 在 守护 进程 模式 中 不 能 使 用 WsGIPythonPath。 应 该 使 用 WSGIDaemonProcess 指令 的 python-path 选 
项 ， 例如 : 








WSGIDaemonProcess example.com python-path=/path/to/mysite.com: /path/to/venv/Llib/python2.7/ 
site-packages 
WSGIProcessGroup example.com 


设置 守护 进程 模式 的 详细 说 明 参 见 mod_wsgi 官方 文档 。 





13.11 在 生产 环境 中 伺服 文件 


Django 本 身 不 伺服 文件 ， 而 是 交 给 你 选择 的 Web 服务 器 。 建 议 使 用 单独 的 Web 服务 器 〈 即 不 负责 运行 Djan- 
go 的 服务 器 ) 伺服 媒体 文件 。 下 面 是 两 个 不 错 的 选择 : 
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然而 ， 如 果 你 别 无 选择 ， 只 能 在 运行 Django 的 Apache 虚拟 主机 中 伺服 媒体 文件 ， 可 以 让 Apache 把 某 些 
URL 视 作 静态 媒体 文件 ， 其 它 URL 则 使 用 Django 的 mod_wsgi 接口 伺服 。 




















下 述 示例 把 Django 放 到 网 站 根 目 录 中 ， 但 是 明确 指明 把 robots.txt、favicon.ico、CSS 文件 ， 以 及 /stat- 
ic/ 和 /media/ 目录 中 的 文件 视 作 静态 文件 。 除 此 之 外 的 URL 都 使 用 mod_wsgi 伺服 。 














Alias /robots.txt /path/to/mysite.com/static/robots.txt 
Alias /favicon.ico /path/to/mysite.com/static/favicon.ico 


Alias /media/ /path/to/mysite.com/media/ 
Alias /static/ /path/to/mysite.com/static/ 


<Directory /path/to/mysite.com/static> 
Require all granted 
</Directory> 
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<Di 


Require all granted 


</Director 


/> 


rectory /path/to/mysite.com/media> 


WSsGIScriptAlias / /path/to/mysite.com/mysite/wsgi.py 


<DL 


<Files wsgi.py> 
Require all granted 
</Files> 
</Directory> 


ectory /path/to/mysite.com/mysite> 














如 果 使 用 的 Apache 版 本 低 于 2.4， 把 Require all granted 替换 成 Allow from all， 并 在 前 面 一 行 添加 0rder 


deny ,allow, 


13.11.1 伺服 管理 后 台 的 文件 


























如 果 django.contrib.staticfiles 在 INSTALLED_APPS 中 ，Django 开发 服务 器 自动 伺服 管理 后 台 (以 及 安装 的 


其 他 应 用 ) 的 静态 文件 。 在 其 他 环境 中 则 不 然 ， 为 了 伺服 管理 


使 用 的 其 他 Web 服务 器 。 








管理 后 台 的 静态 文人 
files 处 到 
令 收 集 STATIC_ROOT 中 的 静态 文 从 














之 外 还 有 三 种 方案 : 


1， 在 文档 根 目 录 中 创建 一 个 符号 链接 ， 指 向 管理 
使 用 +fFoLLowSymLinks) 。 

2. 使 用 Alias (如 前 所 示 ) 为 相应 的 URL 创 妈 
文件 的 真正 位 置 。 

3. 复制 管理 后 台 的 静态 文 伯 






























































F 在 django/contrib/admin/static/admin 日 








F， 然 后 配置 Web 月 












































FEF， 放 到 Apache 的 文档 根 目 录 中 。 


13.11.2 如 果 遇 到 UnicodeEncodeError 异常 





加 细 





你 使 

















Django 的 国 




















际 化 功能 ， 而 


别名 (可 能 是 STATIC_URL + admin/) ， 指 向 管理 后 台 吏 克 























且 允 许 用户 上 传 文件 ， 必 须 而 


























后 台 的 静态 文件 ， 你 要 自行 设置 Apache 或 你 





PA。 我们 强烈 建议 使 用 django.contrib.static- 
E 管 理 后 台 的 静态 文件 (如 前 一 节 所 述 ， 也 交 给 Web 服务 器 ， 为 此 ， 要 使 用 collectstatic 管理 命 
民 务 器 ， 在 STATIC_URL 上 伺服 STATIC_ROOT) ， 不 过 除 此 




















后 台 的 静态 文件 目录 (可 能 要 在 Apache 的 配置 文件 中 


外 








CE 


保 Apache 所 在 的 环境 接受 非 ASCI 文件 


名 。 如 果 没 有 正确 配置 环境 ， 使 用 os .path 中 的 函数 处 理 包 含 非 ASCII 字符 的 文件 名 时 会 触发 UnicodeEn- 


codeError 异常 。 



































为 了 避免 这 类 问题 ， 启 动 Apache 的 环境 应 该 做 类 似 下 面 的 配置 . 


这 些 配 置 项 目 
在 环境 





录 oo 


export LANG='en_US.UTF-8' 
export LC_ALL='en_US.UTF-8' 











| 

















EE 启 Apache。 








13.12 在 生产 环境 伺服 静态 文件 





在 生产 环境 中 伺服 静态 文件 的 过 程 很 简 自 
录 (STATIC_ROOT) 中 收集 到 的 文 从 





























的 具体 句法 和 存放 位 置 参阅 操作 系统 的 文档 。 在 Unix 平台 中 通常 放 在 /etc/apache2/envvars 目 
添加 上 述 配 置 之 后 ， 习 





























和 静态 文件 有 变化 时 和 运行 collectstatic 命令 ， 然 后 把 静态 文件 目 
F 移 到 静态 文件 服务 器 中 伺服 。 
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根据 STATICFILES_STORAGE 设置 的 不 同 ， 你 可 能 要 自己 动手 把 静态 文件 移 到 新 位 置 ， 或 者 让 Storage 类 的 
post_process 方法 代劳 。 


当然 ， 与 所 有 部 署 任 务 一 样 ， 细 节 是 最 麻烦 的 。 每 个 生产 环境 多 少 都 有 点 区 别 ， 因 此 你 要 根据 自己 的 需求 调 
整 上 述 基本 过 程 。 


























下 面 讨论 几 种 常见 做 法 ， 和 希望 能 给 你 一 些 帮助 。 


13.12.1 使 用 同一 个 服务 器 伺服 网 站 和 静态 文件 


如 果 想 使 用 伺服 网 站 的 服务 器 伺服 静态 文件 ， 这 个 过 程 可 能 是 这 样 的 : 























。 把 代码 推送 到 服务 器 中 。 
。 在 服务 器 中 运行 collectstatic 命令 ， 把 所 有 静态 文件 复制 到 STATIC_ROoT 目录 中 。 
。 配置 Web 服务 器 ， 在 STATIC_URL 上 伺服 STATIC_ROOT。 














你 可 能 想 让 这 个 过 程 实现 自动 化 ， 尤 其 是 有 多 个 Web 服务 器 时 。 自 动 化 有 很 多 方法 ， 多 数 Django 开发 者 喜 
欢 使 用 Fabric。 

















下 面 ， 以 及 后 续 几 小 节 将 展示 几 个 fabfile ( 即 Fabric 脚本 ) 示例 ， 说 明 如 何 自动 部 署 静态 文件 。fabfile 的 名 
法 相当 简单 ， 不 再 更 述 。 如 果 想 全 面 了 解 句法 ， 请 阅读 Fabric 的 文档 。 把 静态 文件 部 署 到 多 个 Web 服务 器 的 
fabfile 可 能 是 下 面 这 样 的 : 























from fabric.api import * 


# 目标 主机 
env.hosts = ['www1.example.com', 'www2.example.com'] 


# 项 目 代码 在 服务 器 中 的 位 置 


env.project_root = '/home/www/myproject' 
def deploy_static(): 


with cd(env.project_root): 
run('./manage.py collectstatic -vO --noinput') 


13.12.2 使 用 专门 的 服务 器 伺服 静态 文件 


多 数 大 型 Django 网 站 使 用 单独 的 Web 服务 器 〈 即 运行 Django 之 外 的 服务 器 ) 伺服 静态 文件 。 静 态 文 件 专用 
的 服务 器 通常 运行 速度 更 快 、 但 功能 不 是 那么 全 面 的 Web 服务 器 。 常 见 的 选择 有 : 
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本 书 不 讲 如 何 配 置 这 些 服务 器 ， 详 细 说 明 参 见 各 服务 器 的 文档 。 因 为 静态 文件 服务 器 不 运行 Django， 所 以 把 
部 署 策略 修改 成 下 面 这 样 : 





1 静态 文 件 有 变化 时 在 本 地 运行 collectstatic 命令 。 


2， 把 本 地 的 STATIC_ROOT 推送 到 静态 文件 服务 器 中 用 于 伺服 的 目录 里 。 这 一 步 通 常 使 用 rsync， 因 为 只 需 
要 传输 有 变化 的 静态 文件 。 



































此 时 ，fabfile 如 下 所 示 : 
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from fabric.api import * 


from fabric.contrib import project 


# 静态 文件 在 本 地 的 位 置 ， 即 STATIC_ROOT 设置 
env.local_static root = '/tmp/static' 


# 静态 文件 在 远程 服务 器 中 的 位 置 


env.remote_static_root = '/home/www/static.example.com 


@roles('static') 


def deploy_static(): 


local('./manage.py collectstatic') 


project.rsync_project( 


remote dir = env.remote static root, 


local_dir = env.local static root, 


delete = True 


) 


13.12.3 使 用 云 服务 或 CDN 伺服 静态 文件 


另 一 种 常见 的 策略 是 使 用 云 存 储 提供 商 (如 Amazon 的 S3) 和 (或 ) CDN (Content Delivery Network， 内 容 
分 发 网 络 ) 伺服 静态 文件 。 采 用 这 种 方式 ， 你 无 须 费心 伺服 静态 文件 ， 而 且 网 页 加 载 的 速度 通常 更 快 (使 用 
CDN 时 更 是 如 此 ) 。 


使 用 这 些 服 务 时 ， 基 本 的 了 
上 传 到 存储 提供 商 或 CDN 中 。 
端 ， 极 大 地 简化 这 个 过 程 。 











如 果 你 自己 编写 了 存储 后 端 ， 或 者 使 
警 ， 供 collectstatic 使 用 。 假 如 你 写 的 S3 存储 后 端 用 














[ 作 流 程 与 前 1 












































下 很 像 ， 但 是 不 再 使 用 rsync 传输 静态 文件 ， 而 是 要 自己 把 静态 文件 
这 一 步 有 很 多 做 法 ， 不 过 如 果 提 供 商 有 API 的 话 ， 可 以 自 定义 文件 存储 后 















































第 三 方 存 储 后 端 ， 可 以 把 STATICFILES_STORAGE 设 为 自 定义 的 存储 引 
E myproject.storage.S3Storage 中 ， 可 以 这 么 设置 : 





STATICFILES_STORAGE = 'myproject.storage.S3Storage' 


设置 好 之 后 ， 只 需 运 行 collectstatic 命令 ， 这 样 静态 文件 就 会 通过 指定 的 存储 后 端 推 送 到 S3 中 。 如 果 以 后 















































想 换 成 其 他 存储 提供 商 ， 只 需 修 改 STATICFILES_STORAGE 设置 。 很 多 常用 的 文件 存储 API 都 有 第 三 方 应 用 提 














13.13 弹性 伸缩 


现在 ， 我 们 知道 如 何在 和 








个 服务 器 中 运行 Django 了 。 





供 存储 后 端 。 你 可 以 到 Django Packages 中 找 一 找 。 




















F 面 说 明 如 何 弹性 伸缩 。 本 节 说 明 如 何 把 网 站 部 署 到 大 


规模 集群 中 ， 以 便 每 小 时 伺服 百 万 级 访问 。 然 而 ， 要 知道 ， 各 个 大 型 网 站 之 间 是 有 区 别 的 ， 因 此 没有 完全 通 





用 的 做 法 。 









































接 下 来 的 内 容 说 明 常规 的 原则 ， 以 及 何 时 可 以 选用 其 他 方案 。 首 先 ， 我 们 专 讲 使 用 Apache 和 mod_python 时 
如 何 弹性 伸缩 一 一 这 是 大 前 提 。 虽 然 有 很 多 中 大 型 网 站 使 用 FastCGI， 但 是 我 们 对 Apache 更 熟悉 。 

















13.13.1 在 单个 服务 器 中 运行 











多 数 网 站 一 开始 在 和 





之 间 很 快 就 会 





























个 服务 器 中 运行 ， 采 用 的 架构 类 似 于 
bt 现 资源 况 儿 


(resource contention ) 四 























图 13-1。 然 而 ， 随 着 流量 的 增加 ， 软 件 的 不 同 部 分 
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图 13-1，Django 在 单个 服务 器 中 的 架构 


数据 库 服务 器 和 Web 服务 器 都 喜欢 独占 整个 服务 器 ， 如 果 在 同一 个 服务 器 中 运行 ， 它 们 会 争 用 资源 
(RAM、CPU) ， 都 想 占 为 已 有 。 把 数据 库 服务 器 移 到 单独 的 设备 中 就 能 轻易 解决 这 个 问题 。 








13.13.2 把 数据 库 服务 器 独立 出 来 


对 Django 来 说 ， 把 数据 库 服务 器 独立 出 来 的 过 程 极 其 简单 ， 只 需 把 DATABASE_H0ST 设置 改 为 数据 库 服 务 器 的 
IP 或 DNS。 如 果 可 能 ,使 用 IP 最 好 ， 不 推荐 使 用 DNS 连接 Web 服务 器 和 数据 库 服务 器 。 数 据 库 服务 器 独 
立 后 ， 架 构 如 图 13-2 所 示 。 











媒体 


Web 服务 器 


数据 库 


数据 库 服 务 器 


图 13-2， 把 数据 库 移 到 专门 的 服务 器 中 
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这 就 是 我 们 经 常 说 的 n 层 (ntier) 架构 。 别 被 这 个 术语 吓 到 了 ， 它 的 意思 就 是 把 Web 栈 的 不 同 层 分 到 不 同 
的 物理 设备 中 。 























此 时 ， 如 果 预 期 将 使 用 多 个 数据 库 服 务 器 ， 或 许 应 该 开始 考虑 连接 池 和 (或 ) 数据 库 复 制 (database replica- 
tion) 。 可 惜 ， 本 书 没 有 足够 的 篇 幅 探讨 这 个 话题 ， 如 果 你 想 进 一 步 了 解 ， 可 以 阅读 数据 库 的 文档 ， 或 者 寻 
求 社区 的 帮助 。 

















13.13.3 使 用 单独 的 服务 器 伺服 媒体 文件 


单个 服务 器 还 有 一 个 大 问题 没有 考虑 到 : 媒体 文件 和 动态 内 容 在 同一 个 服务 器 中 处 理 。 这 两 方面 若 想 都 获得 
最 好 的 性 能 ， 需 要 不 同 的 环境 ， 如 果 挤 在 一 起 ， 性 能 上 可 谓 两 败 俱 伤 。 














因此 ， 还 要 把 媒体 文件 独立 出 去 ， 即 把 不 是 Django 视图 生成 的 内 容 移 到 专门 的 服务 器 中 〈 见 图 13-3) 。 











理想 情况 下 ， 媒 体 服务 器 最 好 使 用 简化 版 Web 服务 器 ， 并 且 要 做 优化 ， 能 直接 伺服 静态 媒体 文件 。 这 里 ， 
Nginx 是 最 好 的 选择 ， 不 过 使 用 lighttpd 或 极度 简化 的 Apache 也 行 。 对 静态 内 容 (照片 、 视 频 ， 等 等 ) 较 多 
的 网 站 来 说 ， 单 独 使 用 一 个 媒体 文件 服务 器 更 加 重要 ， 而 且 在 弹性 伸缩 时 ， 应 该 放 在 第 一 步 。 



























































不 过 ， 这 个 过 程 可 能 很 棘手 。 如 果 应 用 程序 允许 上 传 文件 ，Dijango 要 能 够 把 上 传 的 媒体 文件 写 人 媒体 服务 
器 。 如 果 媒 体 文件 存 贮 在 另 一 个 服务 器 中 ， 要 提供 一 种 方式 ， 以 便 通 过 网 络 写 数据 。 














Web 服务 器 媒体 服务 器 


数据 库 


数据 库 服务 器 


图 13-3， 把 媒体 服务 器 独立 出 去 


13.13.4 实现 负载 均衡 和 元 余 


目前 ， 我 们 尽 可 能 做 了 分 解 。 这 种 三 服务 器 架构 应 该 能 处 理 相当 多 的 流量 了 〈 我 们 的 一 个 网 站 使 用 这 种 架 
构 ， 每 天 能 伺服 一 千 万 左右 的 访问 量 ) ， 如 果 网 站 进一步 扩容 ， 需 要 添加 元 余 了 。 
































宛 余 确实 是 个 好 东西 。 看 一 眼 图 13-3， 你 会 发 现 ， 即 便 三 个 服务 器 中 有 一 个 宕 机 了 ， 整 个 网 站 都 将 无 法 访 
间 。 因 此 ， 添 加 匈 余 服务 器 不 仅 增 加 了 容量 ， 还 提升 了 可 靠 性 。 这 里 ， 我 们 暂且 假设 Web 服务 器 首先 达到 容 
量 瓶 颈 。 



































在 不 同 的 硬件 中 运行 多 份 Django 网 站 比较 简单 





只 需 把 代码 复制 到 多 台 设 备 中 ， 然 后 在 各 台 设 备 中 启动 
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Apache。 不 过 ， 你 还 需要 一 种 软件 ， 通 过 它 把 流量 分 发 给 多 人 台 服务 器 ， 即 负载 均衡 程序 (load balancer) 。 


你 可 以 花 钱 购买 专用 的 硬件 负载 均衡 程序 ， 不 过 也 有 一 些 高 质量 的 开源 负载 均衡 程序 可 用 。Apache 的 
mod_proxy 就 是 其 中 一 个 ， 不 过 笔者 觉得 Perlbal 更 好 。Perlbal 是 一 个 负载 均衡 程序 和 反 向 代理 ， 由 mem- 
cached (参见 第 16 章 ) 的 开发 者 们 编写 。 


We 服务 器 集群 化 之 后 ， 得 到 的 结构 更 为 复杂 ， 如 图 13-4 所 示 。 


























负载 均衡 程序 媒体 服务 器 


LA | 


(ejlslalele) (ejflalele) (ejfslalele) 





Web 服务 器 集群 


数据 库 


数据 库 服 务 器 


图 13-4， 负 载 均衡 的 元 余 服务 器 架构 





注意 ， 图 中 把 多 台 Web 服务 器 称 为 一 个 集群 ， 以 此 表明 Web 服务 器 的 数量 基本 上 是 可 变 的 。 在 前 面 加 上 负 
载 均衡 程序 之 后 ， 可 以 轻易 添加 和 删除 后 端 Web 服务 器 ， 一 秒 也 不 用 停机 。 

















13.13.5 发 展 壮 大 
接 下 来 ， 可 以 考虑 以 下 几 件 事 : 
。 如 果 想 进一步 提升 数据 库 的 性 能 ， 可 以 复制 数据 库 服务 器 。MySQL 内 建 支持 复制 ，PostgreSQL 用 户 
可 以 使 用 Slony 复制 数据 库 ， 使 用 pgpool 管理 连接 池 。 
。 如 果 一 个 负载 均衡 程序 不 够 用 ， 可 以 在 前 面 添加 多 个 ， 然 后 使 用 循环 (round-robin) DNS 在 各 个 负载 
均衡 程序 之 间 分 发 。 
。 如 果 一 个 媒体 服务 器 不 够 用 ， 可 以 添加 多 个 ， 然 后 使 用 负载 均衡 集群 分 发 负载 。 
。 如 果 需 要 更 多 的 缓存 存储 器 容量 ， 可 以 添加 专门 的 缓存 服务 器 。 
。 任何 时 候 ， 只 要 觉得 集群 的 性 能 不 够 ， 就 可 以 在 集群 中 添加 更 多 服务 器 。 
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这 样 调整 之 后 ， 大 规模 集群 架构 类 似 于 图 13-5。 
虽然 图 中 在 每 一 层 只 给 出 了 两 三 个 服务 器 ， 但 是 你 可 以 添加 更 多 ， 每 一 层 基 本 上 没有 数量 限制 。 





EE ED EE . ED 本 开 


负载 均衡 集群 媒体 服务 器 集群 


sss 


一 一 一 和 


Web 服务 器 集群 缓存 集群 






database database 


数据 库 服务 器 集群 


图 13-5， 大 规模 Django 架构 示例 


13.14 性 能 调 优 


如 果 对 你 来 说 钱 不 是 问题 ， 弹 性 伸缩 时 只 需 投资 更 多 的 硬件 。 但 是 ， 一 般 来 说 ,我们 的 资金 是 有 限 的 ， 因 此 
必须 调 优 性 能 。 


如 果 阅 读本 书 的 你 碰巧 手 握 巨 资 ， 请 考虑 给 Django 基金 会 捐 一 笔 。 他 们 也 接受 未 经 切割 的 销 
石和 金 元 宝 。 














可 是 ， 性 能 调 优 是 一 门 艺术 而 非 科 学 ， 与 弹性 伸缩 相 比 ， 更 难道 出 个 所 以 然 。 如 果 你 真 想 部 署 大 型 Django 应 
用 程序 ， 必 须 花 大 量 时 间 学 习 如 何 调 优 各 个 部 分 。 





不 过 ， 接 下 来 的 几 小 节 将 讨论 这 些 年 笔者 发 现 的 一 些 对 Django 来 说 行 之 有 效 的 调 优 技巧 。 


13.14.1 RAM 不 嫌 多 


曾经 昂贵 的 RAM 如 今 我 们 都 能 负担 得 起 了 。 尽 你 所 能 ， 尽 量 多 购买 RAM， 越 多 越 好 。 处 理 需 再 快 也 提升 不 
了 多 少 性 能 ， 对 多 数 Web 服务 器 来 说 ，90% 的 时 间 都 在 等 待 磁盘 WO。 一 旦 开始 使 用 交换 内 存 ， 性 能 便 会 急 
剧 下 降 。 速 度 更 快 的 磁盘 可 能 有 点 帮助 ， 但 是 价格 比 RAM 贵 ， 因 此 没 必 要 在 磁盘 上 投资 太 多 。 

















如 果 有 多 个 服务 器 ， 首 先 应 该 为 数据 库 服务 器 增加 RAM。 如 果 你 能 负担 得 起 ， 多 加 一 些 RAM， 把 整个 数据 
库 都 载 和 内存。 这 没什么 问题 ， 笔 者 开发 的 一 个 网 站 有 50 多 万 篇 新 闻 稿 ， 而 空间 只 占 了 2GB。 


其 次 ， 尽 量 为 Web 服务 器 增加 RAM。 理 想 的 情况 是 绝 不 使 用 交换 内 存 。 如 果 达 到 这 个 水 平 ， 你 就 能 应 付 大 
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多 数 正 常 的 流量 。 





13.14.2 禁用 Keep-Alive 





Keep-Alive 是 HTTP 的 一 个 特性 ， 目 的 是 让 多 个 HTTP 请 求 通过 一 次 TCP 连接 伺服 ， 从 而 避免 接 断 TCP 时 
的 消耗 。 乍 一 看 ， 这 是 个 好 主意 ， 但 是 Django 网 站 的 性 能 可 能 受到 影响 。 如 果 使 用 单独 的 服务 器 伺服 媒体 文 
件 ， 用 户 浏览 你 的 网 站 时 ， 差 不 多 每 十 秒 才 会 从 Django 服务 器 中 请 求 一 个 页 面 。 这 样 ，HTTP 服务 器 要 一 直 
等 待 下 一 个 请 求 ， 而 空闲 的 HITP 服务 器 与 工作 时 消耗 的 RAM 一 样 多 。 















































13.14.3 使 用 memcached 




















尽管 Django 支持 不 同 的 缓存 后 端 ， 但 是 它们 都 没有 memcached 速度 快 。 如 果 你 的 网 站 流量 很 大 ， 别 考虑 其 
他 后 端 ， 使 用 memcached 就 对 了 。 











13.14.4 经 常 使 用 memcached 























当然 ， 如 果 不 用 ，memcached 就 是 个 摆设 。 第 16 章 将 详细 说 明 如 何 使 用 Django 的 缓存 框架 ， 以 及 如 何 尽量 
多 地 使 用 。 在 大 流量 下 ， 往 往 只 有 优先 抢占 式 缓存 才能 保住 网 站 不 宕 机 。 



































13.14.5 参与 其 中 


Django 栈 的 每 一 个 组 成 部 分 ， 从 Linux 到 Apache， 到 PostgreSQL 或 MySQL ， 背 后 都 有 非常 棒 的 社区 。 如 果 
你 真 想 榨 二 服务 器 的 性 能 ， 参 与 软件 背后 的 开源 社区 ， 向 社区 中 的 人 寻求 帮助 。 免 费 软件 社区 的 多 数 成 员 都 
乐于 助人 。 别 忘 了 加 入 Django 社区 ， 这 里 聚集 着 一 群 极 具 活 力 的 Django 开发 者 ， 一 直 在 发 展 壮大 ， 有 大 量 
经 验 等 着 传授 给 你 。 




















































































































13.15 接 下 来 

















余下 的 几 章 讨论 你 可 能 用 得 到 也 可 能 用 不 到 的 Django 功能 ， 你 可 以 根据 需要 以 任何 顺序 阅读 。 
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第 14 章 生成 非 HTML 内 容 














当 我 们 讨论 开发 网 站 时 ， 通 常 指 的 是 生成 HIML。 当 然 ， 除 了 HTML，Web 中 还 有 很 多 其 他 内 容 。 我 们 通过 
Web 分 发 各 种 格式 的 数据 ， 例 如 RSS、PDF、 图 像 ， 等 等 。 


目前 ， 我 们 讨论 的 是 常规 情况 ， 即 生成 HTML， 不 过 本 章 将 换个 话题 ， 说 明 如 何 使 用 Django 生成 其 他 类 型 
的 内 容 。Django 为 下 列 常用 的 非 HTML 内 容 提 供 了 内 置 工具 : 










































































。 逗号 分 隔 的 文件 (CSV) ,便于 导入 电子 表格 应 用 程序 

。 PDF 文件 

。 RSS/Atom 订阅 源 

。 网 站 地 图 (一 种 XML 格式 的 文件 ， 最 初 由 Google 开发 ， 作 用 是 为 搜索 引擎 指 路 ) 






































后 文 会 分 述 这 些 工 具 ， 不 过 在 此 之 前 我 们 先 来 了 解 一 些 基 本 的 原则 。 











14.1 基础 知识 ， 视 图 和 MIME 类 型 





第 2 章 说 过 ， 视 图 函数 就 是 普通 的 Python 函数 ， 它 接受 一 个 Web 请 求 为 参数 ， 返 回 一 个 Web 响应 。 响 应 可 
以 是 网 页 的 HTML 内 容 、 重 定向 、404 错误 、XML 文档 、 图 像 ， 等 等 。 更 为 正式 地 说 ，Django 视图 必须 满 
足下 述 两 个 条 件 : 








1. 第 一 个 参数 为 一 个 HttpRequest 实例 





2.， 返回 一 个 HttpResponse 实例 








让 视图 返回 非 HTML 内 容 的 关键 在 于 HttpResponse 类 ， 尤 其 是 content_type 参数 。Django 默认 把 con- 
tent_type 的 值 设 为 "text/htmL"。 不 过 ， 你 可 以 把 它 设 为 官方 的 媒体 类 型 (MIME 类 型 ， 由 IANA 管理 ) 中 
的 任何 一 个 值 。 


调整 MIME 类 型 的 目的 是 告诉 浏览 器 ， 返 回 的 响应 是 其 他 格式 。 例 如 ， 下 述 视 
起 见 ， 我 们 直接 从 磁盘 中 读 取 图 像 文 件 。 
































A 
赔 


回 一 张 PNG 图 像 。 简 单 





























from django.http import HttpResponse 


def my_image(request): 
image_data = open("/path/to/my/image.png", "rb").read() 
return HttpResponse(image_data, content_type="image/png") 












































就 这 么 简单 ! 如 果 你 把 open() 调用 中 的 图 像 路 径 换 成 真实 的 路 径 ， 通 过 这 个 简单 的 视图 就 能 伺服 一 张 图 像 ， 
浏览 器 能 正确 把 它 显示 出 来 。 






































还 要 知道 的 一 点 是 ，HttpResponse 对 象 实现 了 Python 的 标准 文件 类 对 象 API。 这 意味 着 ， 在 Python (或 第 三 
方 库 ) 期 待 文件 的 地 方 都 可 以 使 用 HttpResponse 实例 。 下 面 通过 示例 说 明 如 何 让 Django 生成 CSV 文件 。 
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14.2 生成 CSV 文件 





Python 自 带 了 一 个 CSV 库 ，csv。 在 Django 中 之 所 以 能 使 用 它 创建 CSV 文件 ， 是 因为 csv 模块 操作 的 是 类 




















似 文件 的 对 象 ， 而 Django 上 pRBsponse 对 象 就 是 类 似 文件 的 对 象 。 下 面 举 个 例子 : 














import csv 
from django.http import HttpResponse 


def some_view(request): 
# 使 用 恰当 的 CSV 首部 创建 HttpResponse 对 象 
response = HttpResponse(content_type='text/csv') 
response[ 'Content-Disposition'] = 'attachment; 
filename="somefilename.csv"' 


writer = csv.writer(response) 
writer.writerow(['First row', 'Foo', 'Bar', 'Baz']) 


writer.writerow(['Second row', 'A', 'B', 'C', '"Testing"']) 


return response 


这 段 代 码 和 注释 不 解 自明 ， 不 过 有 些 地 方 需要 注意 : 



































。 响应 的 MIME 类 型 是 text/csv。 它 的 目的 是 告诉 浏览 器 ， 这 是 一 个 CSV 文件 ， 


而 不 是 HTML 文件 。 








如 果 不 这 样 设 定 ， 浏 览 器 可 能 会 把 输出 解释 为 HIML， 在 浏览 器 窗口 中 显示 杂乱 无 章 的 内 容 。 
。 还 为 响应 设 定 了 Content-Disposition 首部 ， 其 值 包含 CSV 文件 的 名 称 。 文 件 名 可 以 根据 需要 随意 











起 。 浏 览 器 调用 另存 为 对 话 框 时 会 使 用 这 个 名 称 。 




















。 调用 生成 CSV 的 API 很 简单 ， 只 需 把 response 作为 第 一 个 参数 传 给 csv.writer 函数 。 这 个 函数 期 待 














参数 是 一 个 类 似 文件 的 对 象 ， 而 HttpResponse 对 象 正 是 这 样 的 对 象 。 








。 CSV 文件 中 的 每 一 行 通过 一 次 writer .writerow 调用 写 入 ， 传 给 它 的 参数 是 一 个 可 迭代 对 象 ， 例 如 列 


表 或 元 组 。 





writerow() 函数 ， 它 能 正确 处 理 。 





14.2.1 以 流 的 形式 发 送 大 CSV 文件 











csv 模块 会 代为 添加 引号 ， 因 此 你 不 用 担心 转 义 包 含 引 号 或 逗号 的 字符 串 。 只 需 把 原始 字符 串 传 给 


如 有 果 视 图 生成 特别 大 的 响应 ， 可 能 要 考虑 使 用 Django 的 StreamingHttpResponse。 例 如 ， 如 果 生 成 文件 所 用 
的 时 间 很 长 ， 负 和 载 均衡 程序 可 能 会 切断 连接 ， 以 防 生 成 响应 时 超时 ， 以 流 的 形式 发 送 文件 则 能 避免 这 种 问 
题 。 在 下 述 示例 中 ， 我 们 充分 利用 Python 生成 器 高 效 处理 大 型 CSV 文件 的 生成 和 传输 : 



































import csv 


from django.utils.six.moves import range 
from django.http import StreamingHttpResponse 


class Echo(object): 
"""An object that implements just the write method of the file-like 
interface, 


Wn 


def write(self, value): 


"""Write the value by returning it, instead of storing in a buffer. 
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return VaLue 


def some_streaming_csv_Vview(request): 


"""A view that streams a Large CSV file. 
# 生成 行 序列 
# 范围 根据 多 数 电子 表格 应 用 程序 在 单个 表 中 能 处 理 的 行 数 而 定 
rows = (["Row {}".format(idx), str(idx)] for idx in range(65536)) 
pseudo_buffer = Echo() 
writer = csv.writer(pseudo_buffer) 
response = StreamingHttpResponse((writer .writerow(row) 
for row in rows), content_type="text/csv") 
response[ 'Content-Disposition'] = 'attachment; 
filename="somefilename.csv"' 
return response 


14.2.2 使 用 模板 系统 


此 外 ， 还 可 以 使 用 Django 的 模板 系统 生成 CSV。 这 比 使 用 Python 的 csv 模块 低 端 一 些 ， 不 过 为 了 全 面 讲解 
不 同方 式 ， 特 在 此 说 明 。 基 本 思想 是 ， 把 项 目 列表 传 给 模板 ， 让 模板 在 一 个 for 循环 中 输出 逗号 。 下 述 示例 


i 





生成 的 CSV 文件 与 前 面 一 样 : 





























from django.http import HttpResponse 


from django.template import loader, Context 


def some view(request): 





与 前 本 











# 使 用 恰当 的 CSV 首部 创建 HttpResponse 对 象 

response = HttpResponse(content_type='text/csv') 

response[ 'Content-Disposition'] = 'attachment; 
filename="somefilename.csv"' 


# 这 里 ， 数 据 是 硬 编码 的 
# 还 可 以 从 数据 库 或 其 他 源 中 加 载 
csv_data = ( 
("First row', "Fo0', "Bar’,; "Baz  ); 
('Second row', 'A', 'B', 'C', '"Testing"', "Here's a quote"), 


) 
t = loader.get template('my_template_ name.txt') 
c= Context({'data': csv_data,}) 


response.write(t.render(c)) 
return response 


i 的 示例 唯一 的 不 同 是 ， 这 个 示例 使 用 模板 ， 而 不 是 csv 模块 。 其 余 的 代码 ， 如 content_type='text/ 


csv' ， 都 是 一 样 的 。 然 后 ， 创 建 my_template_name.txt 模板 ， 写 人 下 述 代码 : 


{% for row in data %} 


"{{ row.0|addsLashes }}", 
"{{ row.1|laddslashes }}", 
"{{ row.2|addslashes }}", 
"{{ row.3|addslashes }}", 
"{{ row.4|addslashes }}" 


{% endfor %} 
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这 个 模板 十 分 简单 ， 只 是 迁 代 给 定 的 数据 ， 逐 行 显示 CSV 文件 的 内 容 。 这 里 使 用 addslashes 模板 过 滤器 是 
为 了 确保 添加 引号 时 不 出 错 。 


























14.3 其 他 基于 文本 的 格式 


注意 ，CSV 没什么 特别 的 ， 只 是 输出 的 格式 特殊 。 你 可 以 使 用 上 述 方式 输出 任何 基于 文本 的 格式 。 其 
以 使 用 类 似 的 方式 输出 二 进 制 数据 ， 例 如 PDF。 























而 
出 
后 





14.4 生成 PDF 文件 




















Django 能 使 用 视图 动态 输出 PDF 文件 。 在 这 个 过 程 中 要 使 用 优秀 的 开源 Python PDF 库 ReportLab。 动 态 生 成 
PDF 文件 的 好 处 是 ， 可 以 基于 不 同 的 目的 创建 所 需 的 PDF 文件 ， 例 如 为 不 同 的 用 户 生成 不 同 的 内 容 。 


















































14.4.1 安装 ReportLab 


PyPI 中 有 ReportLab 库 。 用 户 指南 (恰巧 是 一 个 PDF 文件 ) 也 可 下 载 。 可 以 使 用 pip 安装 ReportLab : 





$ pip install reportlab 


然后 ， 在 Python 交互 式 解 释 器 中 导 和 人 入， 测试 是 否 成 功 安装 : 








>>> import reportlab 








如 果 这 个 命令 不 抛 出 错误 ， 说 明成 功 安装 了 。 


14.4.2 编写 视图 








在 Django 中 能 使 用 ReportLab 动态 生成 PDF 的 关键 之 处 在 于 ， 与 csv 库 一 样 ，ReportLab API 操作 的 也 是 类 
似 文件 的 对 象 ， 例 如 Django 的 HttpResponse。 下 面 是 一 个 Hello World 示例 : 

















from reportLab.pdfgen import canvas 
from django.http import HttpResponse 


def some_view(request): 
# 使 用 恰当 的 PDF 首部 创建 HttpResponse 对 象 
response = HttpResponse(content_type= 'appLication/pdf ') 
response[ 'Content-Disposition'] = "attachment; 
filename="somefilename.pdf"' 


# 创建 PDF 对 象 ， 把 response 对 象 当 做 “文件 ” 


p = canvas.Canvas(response) 


# 在 PDF 对 象 上 绘制 内 容 ， 即 生成 PDF 
# 全 部 功能 参见 ReportLab 的 文档 
p.drawString(100, 100, "Hello world.") 


# 关闭 PDF 对 象 ， 然 后 收工 
p.showPage() 

p.save() 

return response 
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这 段 代 码 和 注释 不 解 自 明 ， 不 过 


。 响应 的 MIME 类 型 是 application/pdf。 
文件 。 


。 还 为 响应 设 定 了 Content-Disposition 首部 ， 























9 些 地 方 需要 注意 : 




















它 的 目的 是 告诉 浏览 器 ， 这 是 一 个 PDF 文件 ， 而 不 是 HTML 


其 值 包含 PDF 文件 的 名 称 。 文 件 名 可 以 根据 需 


起 。 汶 监 器 调用 另存 为 对 语 框 时 会 使 用 这 个 名 称 。 这 里 ，Content-Disposition 首部 开头 的 值 是 


tachment; '。 这 么 做 的 目的 是 ， 即 便 设备 





框 , 主 
文件 。 


response[ 'Content-Disposition'] = 














。 调用 ReportLab API 很 简 身 


















































是 一 个 类 似 文 件 的 对 象 ， 而 HttpResponse 对 象 ] 























设置 了 默认 使 用 哪个 程序 打开 文件 ， 仍 然 弹出 一 个 对 活 
j 户 决定 怎么 做 。 如 果 没 有 'attachment;' ， 浏 览 器 会 使 用 为 PDF 配置 的 程序 或 插件 打开 PDF 
后 一 种 情况 的 代码 如 下 : 








'filename="somefilename.pdf"' 


和 EE， 只 需 把 response 作为 第 一 个 参数 传 给 canvas .Canvas。Canvas 类 期 待 参 数 





续 生成 PDF 的 方法 都 在 PDF 对 象 (这 里 的 p) 上 调用 ， 而 不 在 response 上 调用 。 


E 是 这 样 的 对 和 象 。 









































。 最 后 ， 记 得 要 在 PDF 对 象 上 调用 showPage() 和 save() 方法 。 





14.4.3 复杂 的 PDF 文件 


使 用 ReportLab 创建 复杂 的 PDF 文件 时 ， 应 该 考虑 使 用 io 库 临时 储存 PDF 文件 。 这 个 库 提 供 类 似 文件 对 象 
的 接口 ， 效 率 特 别 高 。 下 面 是 使 用 io 库 重 写 的 Hello World 示例 : 


from io import BytesIO 





from reportLab .pdfgen import canvas 


from django.http import HttpResponse 


def some_view(request ) : 
# 使 用 恰当 的 PDF 首部 创建 HttpResponse 对 象 
response = HttpResponse(content_ type='application/pdf') 


response[ 'Content-Disposition'] = 'attachm 


filename="somefilename.pdf"' 


buffer = BytesIO() 


# 创建 PDF 对 象 ， 把 BytesI0 对 象 当 做 “文件 ” 
p = canvas.Canvas(buffer) 


# 在 PDF 对 象 上 绘制 内 容 ， 即 生成 PDF 


间 


全 部 功能 
p.drawString(100，100 ， 


关闭 PDF 对 象 


p.showPage() 
p.save() 


参见 ReportLab 的 文档 


"Hello world.") 


# 获取 BytesI0 缓冲 的 值 ， 写 入 响应 
pdf = buffer.getvaLue() 
buffer.cLose() 
response.write(pdf) 


return response 

















ent; 
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14.4.4 其 他 资源 


。 PDFlib 也 是 有 Python 绑 定 的 PDF 生成 库 。 在 Django 中 使 用 的 方式 与 前 文 一 样 。 
。 Pisa XHTML2PDF 也 是 一 个 PDF 生成 库 ， 而 且 提 供 了 集成 到 Django 中 的 示例 。 


























。 HTMLdoc 是 一 个 命令 行 脚本 ， 用 于 把 HTML 转换 成 PDF。 它 没有 Python 接 
术 ， 先 使 用 systen 或 popen 调用 shell 命令 ， 再 使 用 Python 取 回 输出 。 


14.5 其 他 可 和 角 
使 用 Python 能 生成 众多 不 同类 型 的 内 容 。 下 面 简略 说 明 不 同类 型 的 4 


。 ZIP 文件 : Python 标准 库 品 


堆 文 件 ， 








能 











E 成 方式 ， 以 及 所 需 的 库 : 











口 ， 不 过 可 以 采用 迁 回 战 





的 zipfile 模块 能 读 写 压缩 的 ZIP 文件 。 你 可 以 使 用 这 个 模块 按 需 归档 一 


或 者 压缩 大 文档 。 类 似 地 ， 可 以 使 用 标准 库 中 的 tarftte 模块 生成 TAR 文件 。 
。 动态 生成 图 像 : Python Imaging Library (PIL) 是 个 优秀 的 库 ， 用 于 生成 图 像 




















(PNG、JPEG、GIFE， 等 


等 ) 。 可 以 使 用 这 个 库 自动 缩放 图 像 ， 生 成 缩 略图 ， 把 多 个 图 像 合 并 到 一 个 图 框 中 ， 甚 至 还 能 在 Web 























应 用 程序 中 处 理 图 像 。 
。 各 种 图 表 : 有 些 强 大 的 Python 图 表 库 可 以 按 需 生成 地 图 和 图 表 等 图 形 。 这 方 
























































列 出 ， 下 面 给 出 两 个 值得 一 用 的 : 


。 matplotlib 可 用 于 生成 通常 由 MatLab 或 Mathematica 才能 生成 的 高 质量 散 点 图 。 




















面 的 库 太 多 了 ， 无 法 一 一 











。 pygraphviz 是 Graphviz 图 形 布局 工具 包 的 接口 ， 可 用 于 生成 图 形 和 网 络 的 结构 图 。 














一 般 来 说 ， 能 够 写 人 文件 的 Python 库 都 能 在 Django 中 使 用 ， 因 此 有 无 限 可 能 。 


















































非 HTML 内 容 提供 了 十 分 便利 的 生成 工具 。 














14.6 订阅 源 框 架 











Dijango 自 带 了 








XML 的 格式 ， 用 于 





















































至 此 ， 我 们 简要 说 明了 如 何 生成 非 HTML 内 容 ， 下 面 上 升 一 个 层次 ， 讲 讲 抽象 方面 。Django 为 一 些 常用 的 











个 抽象 的 订阅 源 生成 框架 ， 可 以 轻易 创建 RSS 和 Atom 订阅 源 。RSS 和 Atom 都 是 基于 

















自动 提供 网 站 内 容 的 更 新 源 。RSS 的 详情 参见 这 里 ，Atom 的 详情 参见 这 里 。 





若 想 创建 订阅 源 ， 只 需 编 写 一 个 简短 的 Python 类 。 订 阅 源 的 数量 不 限 。Django 还 为 生成 订阅 源 提供 了 低层 
API。 如 果 想 在 Web 之 外 的 场合 或 者 以 其 他 低层 的 方式 生成 订阅 源 ， 可 以 使 用 这 个 API。 





14.6.1 抽象 框架 








订阅 源 生成 抽象 框架 由 Feed 类 提供 。 若 想 创 建 一 个 订阅 源 ， 编 写 一 个 Feed 的 子 类 ， 


它 的 实例 。 


订阅 源 类 


订阅 源 类 是 表示 订阅 源 的 Python 类 。 订 阅 源 可 以 简单 (例如 网 站 中 的 新 闻 订 阅 源 ， 
订阅 源 ) ， 也 可 以 复杂 (例如 显示 某 一 分 类 中 所 有 博客 文章 的 订阅 源 ， 其 中 分 类 是 可 变 的) 。 订 阅 源 类 是 


django.contrib 














然后 在 URL 配置 中 指向 








或 者 显示 最 新 博客 文章 的 


























URL 配置 中 使 


的 视图 。 











.Syndication.views.Feed 的 子 类 ， 可 以 放 在 代码 基 中 的 任何 位 置 。 订 阅 源 类 的 实例 是 可 以 在 
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一 个 简单 的 示例 
这 个 简单 的 示例 摘自 虚构 的 警 务 新 闻 网 站 ， 用 于 显示 最 新 的 五 篇 新 闻 稿 








from django.contrib.syndication.views import Feed 
from django.core.urlresolvers import reverse 
from policebeat.models import NewsItem 


class LatestEntriesFeed(Feed): 
title = "Police beat site news" 
link = "/sitenews/" 
description = "Updates on changes and additions to police beat central." 


def items(self): 
return NewsItem.objects.order_by('-pub date')[:5] 


def item title(self, itenm): 
return itenm.title 


def item description(self, itenm): 
return item.description 


# 仅 当 NewsItem 未 定义 get_absolute_url 方法 时 才 需 要 item_link 
def item link(self, item): 
return reverse('news-item', args=[item.pk]) 





为 了 在 一 个 URL 上 开放 这 个 订阅 源 ， 要 在 URL 配置 中 添加 这 个 类 的 一 个 对 象 。 例 如 : 





from django.conf.urls import url 
from myproject.feeds import LatestEntriesFeed 


urlpatterns = [ 


sp 
url(r'^latest/feed/$', LatestEntriesFeed()), 
# 。 

] 


。 订阅 源 类 是 django.contrib.syndication.views.Feed 的 子 类 。 
。 title、link 和 description 属性 分 别 对 应 于 RSS 标准 中 的 <titLe>、<Link> 和 <description> 元 素 。 
。 items() 方法 的 作用 很 简单 ， 返 回 一 个 对 象 列表 ， 在 订阅 源 中 以 <item> 元 素 呈 现 。 虽 然 这 个 示例 使 用 


Django 的 对 象 关系 映射 器 返回 一 组 NewsIten 对 象 ， 但 是 不 一 定 非得 返回 模型 实例 。items() 可 以 返回 
任何 类 型 的 对 象 ， 不 过 返回 Django 模型 更 便利 。 


。 如 果 创 建 的 是 Atom 订阅 源 ， 而 不 是 RSS 订阅 源 ， 别 设 定 description 属性 ， 应 该 设 定 subtitle 属 
性 。“ 同 时 提供 Atom 和 RSS 订阅 源 ” 一 节 有 个 例子 。 









































a 


还 有 一 件 事 没 做 。 在 RSS 订阅 源 中 ， 每 个 <item> 中 都 有 <title>、<link> 和 <description>。 我 们 要 告诉 
架 这 些 元 素 中 要 放 什么 数据 。 











为 了 生成 <title> 和 <description> 元 素 的 内 容 ，Django 尝试 调用 订阅 源 类 的 item_title() 和 item_descrip- 
tion() 方法 。 这 两 个 方法 的 参数 都 是 Ltem， 即 对 象 本 身 。 这 两 个 方法 可 以 不 定义 ，Django 默认 使 用 对 象 的 
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Unicode 表示 形式 。 


























如 果 想 在 标题 或 描述 中 使 用 特殊 的 格式 ， 可 以 使 用 Django 模板 。 模 板 的 路 径 由 订阅 源 类 的 title_template 
和 description_template 属性 指定 。 这 两 个 模板 在 泻 染 各 个 条 目 时 调用 ， 而 且 有 两 个 模板 上 下 文 变 量 : 












































。 {{ obj }}: 当前 对 象 (items() 返回 的 对 象 之 一 ) 。 
。 {{ site }}: Django 中 表示 当前 网 站 的 site 对 象 。 可 以 获取 {{ site.domain }} 或 {{ site.name }}。 





“一 个 复 条 的 示例 ”一 节 将 说 明 如 何 使 用 模板 泻 染 描述 。 


除了 上 述 两 个 模板 变量 之 外 ， 如 果 还 想 为 标题 和 描述 模板 传递 额外 信息 ， 也 有 办 法 : 在 Feed 的 子 类 中 实现 
get_context_data 方法 。 例 如 : 


























from mysite.models import Article 
from django.contrib.syndication.views import Feed 


class ArticlesFeed(Feed): 
title = "My articles" 
description_ template = "feeds/articles.html" 


def items(self): 
return Article.objects.order_by('-pub_date' )[:5] 


def get context data(self, **kwargs): 
context = super(ArticlesFeed, self).get_ context_data(**kwargs) 
Context[ 'foo'] = "bar' 
return context 


模板 : 
Something about {{ foo }}: {{ obj.description }} 


这 个 方法 在 items() 返回 的 各 个 条 目 上 调用 ， 传 人 下 述 关 键 字 参 数 ; 








。 ;item: 当前 条 目 。 为 了 向 后 兼容 ， 这 个 上 下 文 变量 的 名 称 是 {{ obj }}。 


。 obj: get_object() 返回 的 对 象 。 为 了 避免 与 {{ obj }} (参见 上 一 条 ) 混淆 ， 默 认 没 有 把 这 个 变量 开 
放 给 模板 ， 但 是 可 以 在 你 实现 的 get_context_data() 方法 中 使 用 。 


。 site: 如 前 所 述 ， 是 当前 网 站 。 


。 request: 当前 请 求 。 





















































get_context_data() 的 行为 类 似 于 通用 视图 ， 要 调用 super() 从 父 类 中 获取 上 下 文 数据 ， 添 加 数据 后 再 返回 
修改 后 的 字典 。 



































站 定 <Link> 元 素 的 内 容 有 两 种 方式 。 对 items() 返回 的 各 个 条 目 ，Django 首先 尝试 调用 订阅 源 类 的 
item_Link() 方法 。 与 标题 和 描述 类 似 ， 它 的 参数 也 是 item。 如 果 这 个 方法 不 存在 ，Django 尝试 在 条 目 上 调 
用 get_absolute_ur1l()。 











get_absolute_url() 和 item_Link() 都 应 该 以 常规 Python 字符 串 的 形式 返回 条 目的 URL。 与 get_ab- 
solute_url() 一 样 ，item_Link() 的 结果 也 直接 作为 URL 使 用 ， 因 此 你 要 负责 对 URL 做 必要 的 处 理 ， 例 如 添 
加 引号 、 转 换 成 ASCII。 
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一 个 复杂 的 示例 


这 个 框架 也 支持 通过 参数 实现 的 复杂 订阅 源 。 例 如 ， 网 站 可 能 会 为 城市 中 每 个 警 员 最 近 破 获 的 犯罪 活动 提供 
RSS 订阅 源 。 如 果 为 每 个 警 员 都 单独 创建 一 个 订阅 源 类 ， 那 就 太 荒唐 了 。 若 是 真 这 么 做 ， 违 背 了 DRY 原则 
不 说 ， 还 耦合 了 数据 和 程序 设计 逻辑 。 

















其 实 ， 订 阅 源 框架 支持 访问 URL 配置 传 过 来 的 参数 ， 因 此 订阅 源 可 以 根据 URL 中 的 信息 输出 相关 条 目 。 各 
警 员 的 订阅 源 可 以 通过 这 样 的 URL 访问 : 


。 /beats/613/rss/: 返回 613 号 警 员 最 近 破 获 的 犯罪 活动 。 
。 /beats/1424/rss/: 返回 1424 号 警 员 最 近 破 获 的 犯罪 活动 。 























这 种 URL 在 URL 配置 中 可 以 这 样 匹配 : 





url(r'^beats/(?P[0-9]+)/rss/$', BeatFeed()), 





与 视图 类 似 ， 这 里 的 URL 参数 连同 请 求 对 象 一 起 传 给 get_object() 方法 。 各 和 警 员 的 订阅 源 可 以 这 样 实现 : 





from django.contrib.syndication.views import FeedDoesNotExist 
from django.shortcuts import get object or_404 


class BeatFeed(Feed): 
description template = 'feeds/beat description.html' 


def get object(self, request, beat_ id): 
return get object or_404(Beat, pk=beat_id) 


def title(self, obj): 
return "Police beat central: Crimes for beat %s" % obj.beat 


def link(self, obj): 
return obj.get_absolute_url() 


def description(self, obj): 
return "Crimes recently reported in police beat %s" % obj.beat 


def items(self, obj): 
return Crime.objects.filter(beat=0bj).order_by('-crime date')[:30] 





Django 使 用 title()、1link() 和 description() 方法 生成 订阅 源 中 的 <title>、<link> 和 <description> 元 
素 。 

















在 前 面 的 示例 中 ， 这 三 个 元 素 的 内 容 使 用 类 所 
三 个 元 素 时 ，Django 按 下 述 顺序 操作 : 











王 
请 








性 指定 ， 而 这 个 示例 表明 ， 除 此 之 外 还 可 以 使 用 方法 。 生 成 这 

















1. 首先 ， 调 用 相应 的 方法 ， 传 入 obj 参数 。 这 里 的 obj 是 get_object() 返回 的 对 象 。 
2.， 如 果 失 败 ， 尝 试 调用 相应 的 方法 时 不 传人 参数 。 
3. 如 果 失 败 ， 使 用 相应 的 类 属性 。 


























dl 








注意 ，items() 方法 也 是 如 此 : 首先 尝试 items(obj) ， 然 后 尝试 items()， 最 
个 列表 ) 。 这 里 ， 我 们 使 用 模板 生成 条 目的 描述 。 这 个 模板 的 内 容 可 以 非常 


























使 用 items 类 属性 (其 值 为 一 
6 





到 部 














{{ obj.description }} 
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Pe 











不 过 ， 你 可 以 根据 需要 添加 格式 。 下 文 的 ExampleFeed 类 将 详细 说 明 订阅 源 类 的 各 个 方法 和 属性 。 


指定 订阅 源 的 类 型 


b= 








这 个 框架 生成 的 订阅 源 默 认 使 用 RSS 2.0 格式 。 若 想 更 改 ， 在 订阅 源 类 中 请 加 feed_type 属性 ， 如 下 所 示 : 


from django.utils.feedgenerator import Atom1Feed 


class MyFeed(Feed): 
feed type = Atom1Feed 


注意 ，feed_type 的 值 是 一 个 类 对 象 ， 而 不 是 实例 。 目 前 可 用 的 订阅 源 类 型 有 : 





。 django.utitLs.feedgenerator.Rss201rev2Feed (RSS 2.01， 默 认 值 ) 
。 django.utittLs.feedgenerator.RssUserLand091Feed (RSS 0.91 ) 


。 django.utils.feedgenerator .Atom1Feed (Atom 1.0) 


附件 


若 想 指定 附件 ， 例 如 播客 订阅 源 中 的 音频 文件 ， 使 用 item_enclosure_url、item_enclosure_length 和 
item_enclosure_mime_type 钧 子 。 用 法 举例 参见 下 文 的 ExampleFeed 类 。 





这 个 框架 创建 的 订阅 源 会 自动 添加 适当 的 <Language> 标签 (RSS 2.0) 或 xml:lang 属性 (Atom) 。 值 直接 取 
自 LANGUAGE_CODE 设置 。 























URL 


Link 方法 〈 属 性 ) 可 以 返回 一 个 绝对 路 径 (如 /blog/) 或 包含 域名 和 协议 的 完整 URL (如 http://www.exam- 
ple.com/blog/) 。 如 果 Link 的 值 不 包含 域名 ， 订 阅 源 框架 会 根据 SITE_ID 设置 插入 当前 网 站 的 域名 。Atom 
订阅 源 要求 有 个 <Link rel="self">， 定 义 订阅 源 的 当前 位 置 。 订 阅 源 框 架 会 根据 SITE_ID 设置 ， 自 动 把 这 个 
元 素 的 值 设 为 当前 网 站 的 域名 。 


























同时 提供 Atom 和 RSS 订阅 源 








有 些 开发 者 喜欢 同时 提供 Atom 和 RSS 订阅 源 。 在 Django 中 这 很 容易 实现 : 首先 编写 一 个 订阅 源 类 的 子 类 ， 
把 feed_type 属性 设 为 相应 的 值 ， 然 后 在 URL 配置 中 添加 男 一 个 版 本 。 下 面 是 一 个 完整 的 示例 : 





























from django.contrib.syndication.views import Feed 
from policebeat.models import NewsItem 
from django.utils.feedgenerator import Atom1Feed 


class RssSiteNewsFeed(Feed): 
title = "Police beat site news" 
link = "/sitenews/" 
description = "Updates on changes and additions to police beat central." 


def items(self): 
return NewsItem.objects.order_by('-pub_date')[:5] 


class AtomSiteNewsFeed(RssSiteNewsFeed): 
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feed type = Atom1Feed 
subtitle = RssSiteNewsFeed.description 


在 这 个 示例 中 ，RSS 订阅 源 使 用 的 是 description， 而 Atom 订阅 源 使 用 的 是 subtitle。 这 是 
为 Atom 订阅 源 不 提供 整个 订阅 源 的 描述 ， 而 提供 子 标题 。 如 果 在 订阅 源 类 中 设 定 了 de- 
scription，Django 不 会 自动 将 其 用 作 subtitle， 因 为 这 二 者 不 一 定 是 相同 的 。 在 Atom 订阅 源 
中 就 应 该 定义 subtitle 属性 。 





在 上 述 示例 中 ， 我 们 直接 把 Atom 订阅 源 的 subtitle 设 为 RSS 订阅 源 的 description， 因 为 描述 已 经 很 简短 
了 。 相 应 的 URL 配置 如 下 : 


from django.conf.urls import url 
from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed 


urlpatterns = [ 
i 
url(r'^sitenews/rss/$', RssSiteNewsFeed()), 
url(r'^sitenews/atom/$', AtomSiteNewsFeed()), 
和 


] 


订阅 源 类 可 用 的 全 部 属性 和 方法 参见 文档 中 的 示例 。 





14.6.2 低层 API 

抽象 的 订阅 源 框架 在 背后 使 用 低层 API 生成 订阅 源 的 XML。 低 层 API 全 在 django/utils/feedgenerator.py 
一 个 模块 中 。 我 们 可 以 使 用 这 些 API 自己 动手 生成 订阅 源 ， 也 可 以 针对 其 他 的 订阅 源 类 型 自 定 义 生成 订阅 源 
的 子 类 。 


SyndicationFeed 类 及 其 子 类 





feedgenerator 模块 中 有 个 基 类 : 
。 django.utils.feedgenerator .SyndicationFeed 
以 及 它 的 几 个 子 类 : 


。 django.utils.feedgenerator.RssUserland091Feed 
。 django.utils.feedgenerator .Rss201rev2Feed 


。 django.utiLs.feedgenerator .Atom1Feed 


这 三 个 类 都 知道 如 何 泻 染 相应 类 型 的 订阅 源 XML， 它 们 具有 相同 的 接口 : 
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SyndicationFeed. init _() 



































使 用 包含 元 数据 (应 用 于 整个 订阅 源 ) 的 字典 初始 化 订阅 源 。 必 须 的 关键 字 参 数 有 : 





。 title 
。 Link 
。 description 
此 外 还 有 很 多 可 选 的 关键 字 参 数 : 


传 给 _init_ 方法 的 其 他 关键 字 参 数 都 存储 在 self .feed 


language 
author_email 
author_name 
author_Link 
subtitle 
categories 
feed_url 
feed_copyright 
feed_guid 


ttL 


























上 5 可 在 EE 




















定义 的 订阅 源 和 9 


E 成 器 中 使 用 。 所 有 参数 


的 值 都 应 该 是 Unicode 对 象 ， 但 是 categories 例外 ， 它 的 值 应 该 是 Unicode 对 象 序列 。 





SyndicationFeed.add_item() 


使 用 指定 的 参数 创建 一 个 条 目 ， 添 加 到 订阅 源 


UD 





o 





必须 的 关键 字 参 数 有 : 


title 
Link 


description 


可 选 的 关键 字 参 数 有 : 


author_email 
author_name 
author_Link 
pubdate 
comments 
unique_id 
enclosure 


categories 
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。 item copyright 
。 ttl 


。 Updateddate 





其 他 关键 字 参 数 也 会 存储 下 来 ， 以 便 在 自 定义 的 订阅 源 生成 器 中 使 用 。 如 果 指 定 ， 除 了 下 述 参数 之 外 ， 所 有 
参数 的 值 都 应 该 是 Unicode 对 象 : 





。 pubdate 的 值 应 该 是 一 个 Python datetime 对 象 

。 updateddate 的 值 应 该 是 一 个 Python datetime 对 象 

。 enctLosure 的 值 应 该 是 一 个 django.utitLs.feedgenerator.EncLosure 实例 
。 categories 的 值 应 该 是 一 个 Unicode 对 象 序列 


SyndicationFeed.write() 
使 用 指定 的 编码 把 订阅 源 输出 到 类 似 文件 的 对 象 中 。 


SyndicationFeed.writeString() 





以 字符 串 的 形式 返回 指定 编码 的 订阅 源 。 例 如 ， 下 述 代 码 创 建 一 个 Atom 1.0 订阅 源 ， 然 后 打印 到 标准 输出 : 




















>>> from django.utils import feedgenerator 
>>> from datetime import datetime 
>>> f = feedgenerator .Atom1Feed( 
title="My Weblog", 
tink="http://www.example.com/", 
description="In which I write about what I ate today.", 
Language="en", 
author_name="Myself", 
feed_url="http://example.com/atom.xml") 
>>> f.add item(title="Hot dog today", 
Link="http://www.example.com/entries/1/", 
pubdate=datetime .now(), 
description="<p>Today I had a Vienna Beef hot dog. It was pink, plump and per\ 
fect.</p>") 
>>> print(f.writeString('UTF-8')) 
<?xml version="1.0" encoding="UTF-8"?> 
<feed xmlns="http://www.w3.0rg/2005/Atom" xml:lang="en"> 


/feed> 
自 定义 订阅 源 生成 器 
如 果 想 生成 自 定义 的 订阅 源 格式 ， 有 几 个 选择 。 如 果 是 全 新 的 订阅 源 格式 ， 可 以 编写 一 个 SyndicationFeed 


的 子 类 ， 把 write() 和 writeString() 方法 完全 替换 掉 。 然 而 ， 如 果 订 阅 源 格式 派生 自 RSS 或 Atom (如 
GeoRSS、Apple 的 iTunes 播客 格式 ， 等 等 ) ， 有 更 好 的 选择 。 









































这 些 订阅 源 类 型 往往 为 底层 格式 添加 额外 的 元 素 和 (或 ) 属性， 而 SyndicationFeed 为 此 提供 了 一 系列 方 
法 。 因 此 ， 可 以 创建 适当 订阅 源 生成 器 类 (AtomlFeed 或 Rss201rev2Feed) 的 子 类 ， 然 后 扩展 。 这 些 方法 是 : 
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SyndicationFeed.root_attributes(seLf，) 














返回 一 个 属性 字典 ， 添 加 到 订阅 源 的 根 元 素 (feed 或 channel) 中 。 








SyndicationFeed.add_root elements(self, handler) 


向 订阅 源 根 元 素 (feed 或 channel) 中 添加 元 素 的 回调 。handler 是 一 个 XMLGenerator (来 自 Python 内 置 的 
SAX 库 ) ， 添 加 元 素 就 是 在 它 上 面 调用 方法 。 














SyndicationFeed.item attributes(self, item) 

















返回 一 个 属性 字典 ， 添 加 到 各 个 条 目 元 素 (item 或 entry) 中 。 参 数 item 是 一 个 字典 ， 包 含 传 给 Syndica- 
tionFeed.add_item() 的 所 有 数据 。 





SyndicationFeed.add_ item elements(self, handler, item) 


把 元 素 添 加 到 各 个 条 目 (itenm 或 entry) 中 的 回调 。handler 和 iten 同上 。 


如 果 覆 盖 了 这 些 方法 ， 记 得 要 调用 超 类 中 的 方法 ， 因 为 它们 负责 为 各 种 订阅 源 格式 添加 所 需 的 
元 素 。 


例如 ， 可 以 像 这 样 实现 iTunes RSS 订阅 源 生成 器 : 


class iTunesFeed(Rss201rev2Feed): 
def root attributes(self): 
attrs = super(iTunesFeed, self).root attributes() 
attrs['xmlns:itunes'] = 
'http://www.itunes.com/dtds/podcast-1.0.dtd' 
return attrs 


def add_root elements(self, handler): 
super(iTunesFeed, self).add root elements(handler) 
handler .addQuickElement('itunes:explicit', 'clean') 


显然 ， 完 整 的 自 定义 订阅 源 类 还 有 很 多 工作 要 做 ,但 是 上 例 应 该 能 提供 基本 的 思路 。 


14.7 网 站 地 图 框架 


网 站 地 图 是 网 站 中 的 一 个 XML 文件 ， 其 作用 是 告诉 搜索 引擎 索引 程序 网 站 中 页 面 的 更 新 频率 和 重要 程度 。 
这 些 信 息 有 助 于 搜索 引擎 索引 你 的 网 站 。 网 站 地 图 的 更 多 信息 参见 sitemaps.org。 


Django 的 网 站 地 图 框架 通过 Python 代码 表述 这 些 信 息 ， 自 动 生成 网 站 地 图 XML 文件 。 用 起 来 跟 Django 的 
订阅 源 框 架 很 像 。 符 想 创建 网 站 地 图 ， 只 需 编写 一 个 sitemap 子 类 ， 然 后 在 URL 配置 中 指向 它 。 




















14.7.1 安装 
安装 网 站 地 图 应 用 的 步 又 如 下 : 


1， 把 "django.contrib.sitemaps" 添加 到 INSTALLED_APPS 设置 中 。 





220 - 第 14 章 生成 非 HTML 内 容 





2.， 确保 TEMPLATES 设置 中 有 DjangoTemplates 后 端 ， 而 且 它 的 APP_DIRS 选项 设 为 True。 默 认 就 有 这 个 后 
端 ， 除 非 修改 了 这 个 设置 ， 否 则 不 用 动 。 


3.， 安装 网 站 框架 。 











14.7.2 初始 化 





蜂 





若 想 在 Django 网 站 中 生成 网 站 地 图 ， 在 URL 配置 中 添加 下 述 模式 : 














from django.contrib.sitemaps.views import sitemap 


url(r'^sitemap\.xml$', sitemap, {'sitemaps': sitemaps}, 
name='django.contrib.sitemaps.views.sitemap') 




















这 个 URL 模式 的 作用 是 ， 当 客户 端 访问 /sitemap.xml 时 ， 让 Django 构建 一 个 网 站 地 图 。 网 站 地 图 文件 的 名 
称 无 关 紧 要 ， 但 是 位 置 很 重要 。 搜 索引 擎 只 索引 网 站 地 图 中 列 出 的 当前 及 以 下 层级 的 URL。 例如 ， 把 
sitemap.xml 放 在 根 目 录 中 ， 可 以 引用 网 站 中 的 任何 URL， 而 把 网 站 地 图 放 在 /content/sitemap.xml， 则 只 能 
引用 以 /content/ 开头 的 URL。 










































































网 站 地 图 视图 有 个 额外 的 必须 参数 : { "sitemaps' : sitemaps}。sitemaps 应 该 是 个 字典 ， 把 栏目 标签 (如 
blog 或 news) 映射 到 对 应 的 Sitemap 子 类 (如 BLogSitemap 或 NewsSitemap) 上 。 此 外 ， 也 可 以 映射 到 
Sitemap 子 类 的 实例 上 (如 BlogSitemap(some_var)) 。 











14.7.3 网 站 地 图 类 





网 站 地 图 类 是 表示 网 站 地 图 中 一 个 栏目 下 的 条 目的 Python 类 。 例 如 ， 可 以 让 一 个 网 站 地 图 类 表示 博客 中 的 所 
有 文章 ， 让 另 一 个 网 站 地 图 类 表示 日 程 表 中 的 所 有 事项 。 


最 简单 的 情况 是 把 所 有 栏目 放 在 同一 个 sitemap.xml 文件 中 ， 不 过 也 可 以 使 用 这 个 框架 生成 引用 其 他 网 站 地 
图 文件 (一 个 栏目 一 个 ) 的 网 站 地 图 索引 文件 (参见 14.7.8 节 ) 。 


















































网 站 地 图 类 必须 是 django.contrib.sitemaps.Sitemap 的 子 类 。 可 以 放 在 代码 基 的 任何 位 置 。 











14.7.4 一 个 简单 的 示例 


假设 有 个 博客 系统 ， 里 面 有 个 Entry 模型 ， 我 们 想 在 网 站 地 图 中 列 出 指向 各 篇 文章 的 链接 。 此 时 ， 可 以 这 样 
定义 网 站 地 图 类 : 












































from django.contrib.sitemaps import Sitemap 
from blog.models import Entry 


class BlogSitemap(Sitemap): 
changefreq = "never" 
priority = 0.5 


def items(self): 
return Entry.objects.filter(is_draft=False) 


def lastmod(self, obj): 
return obj.pub_date 


活 
le 
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。 类 属性 changefreq 和 priority 分 别 对 应 于 <changefreq> 和 <priority> 元 素 。 如 这 里 的 Lastmod 一 

样 ， 它 们 也 可 以 定义 为 方法 。 

。 items() 返回 对 和 象 列表 。 返 回 的 对 象 将 传 给 网 站 地 图 属性 对 应 的 可 调用 方法 (location、lastmod、 
changefreq 和 priority) 。 

。 lastmod 方法 应 该 返回 一 个 Python datetime 对 象 。 


这 里 没有 定义 location 方法 但是， 如 果 想 指定 对 象 的 URL， 可 以 定义 。 默 认 情 况 下 ，location() 
返回 在 各 个 对 象 上 调用 get_ Sede _url() 得 到 的 结果 。 





























14.7.5 网 站 地 图 类 API 





网 站 地 图 类 可 以 定义 下 述 方法 和 属 ' 


王 
全 
度 
5 








items 








必须 的 。 返 回 对 象 列表 。 网 站 地 图 框架 不 关心 对 象 的 类 型 ， 只 负责 把 这 些 对 象 传 给 location()、lastmod()、 
changefreq() 和 priority() 方法 。 


Location 


























站 


{+ 值 应 该 是 一 











0 


可 选 的。 方法 或 属性 。 如 果 是 方法 ， 应 该 返回 items() 得 到 的 对 象 的 绝对 路 径 ， 如 果 是 属性 ， 
个 字符 串 ， 表 示 items() 返回 的 各 个 对 象 的 绝对 路 径 。 


两 种 情况 下 ， 绝 对 路 径 指 的 都 是 不 含 协议 和 域名 的 URL。 例 如 : 








。 正确 : '/foo/bar/' 





。 错误 : 'example.com/foo/bar/' 
。 错误 : 'http://example.com/foo/bar/' 


如 果 未 提供 location， 网 站 地 图 框架 在 items() 返回 的 各 个 对 象 上 调用 get_absolute_url() 方法 。 如 果 协 议 
不 是 http， 使 用 protocol 指定 。 








Lastmod 








可 选 的 。 方 法 或 属性 。 如 果 是 方法 ， 应 该 接受 一 个 参数 ， 即 items() 返回 的 对 象 之 一 ， 返 回 那个 对 象 的 最 后 
修改 日 期 (时 间 ， 一 个 Python datetime.datetinme 对 象 ) 。 























如 果 是 属性 ， 其 值 应 该 是 一 个 datetime.datetime 对 象 ， 表 示 items() 返回 的 各 个 对 象 的 最 后 修改 日 期 (时 
间 ) 。 如 果 网 站 地 图 中 的 所 有 条 目 都 有 最 后 修改 日 期 ，views.sitemap() 生成 的 网 站 地 图 将 把 Last-Modified 
首部 设 为 最 近 的 最 后 修改 日 期 。 


可 以 激活 ConditionaLGetMiddLeware， 让 Django 根据 If-Modified-Since 首部 响应 请 求 ， 在 网 站 地 图 不 变 时 
不 发 送 。 






















































































changefreq 














可 选 的。 方法 或 属性 。 如 果 是 方法 ， 应 i 
串 ， 表 示 那 个 对 象 的 更 新 频率 ， 如 果 是 大 


不 管 使 用 方法 还 是 属性 ，changefreq 可 以 使 用 的 值 有 : 


一 个 参数 ， 即 items() 返回 的 对 象 之 一 ， 返 回 一 个 Python 字符 
性 ， 其 值 应 该 是 一 个 字符 串 ， 表 示 items() 返回 的 各 个 对 象 的 更 新 





























1 
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。 'always' 


。 'hourly' 

。 'daily' 

。 'weekly' 

e。 'monthly’ 

。 'yearly' 

。 'Never' 
priority 








可 选 的 。 方 法 或 属性 。 如 果 是 方法 ， 应 该 接受 一 个 参数 ， 即 items() 返回 的 对 象 之 








点 数 ， 表 示 那 个 对 象 的 优先 级 。 





























， 返 回 一 个 字符 串 或 浮 





如 果 是 属性 ， 其 值 应 该 是 一 个 字符 串 或 浮 点 数 ， 表 示 items() 返回 的 每 个 对 象 的 优先 级 。priority 的 取 值 示 
例 : 0.4、1.0。 页 面 的 默认 优先 级 是 9.5。 详 情 参 见 sitemaps.org 中 的 文档 。 





protocol 





可 选 的 。 这 个 属性 定义 网 站 地 图 中 的 URL 使 用 什么 协议 (http 或 https) 。 如 
所 用 的 协议 。 如 果 网 站 地 图 在 请 求 上 下 文 之 外 构建 ， 默 认 使 用 http。 











ili8n 














可 选 的 。 这 个 布尔 值 属性 定义 是 否 使 用 LANGUAGES 
FaLse。 








14.7.6 快捷 方式 























设置 中 的 所 有 语言 4 





且 
A 











成 网 站 地 图 中 





未 设 定 ， 使 用 请 求 网 站 地 图 





的 URL。 默 认为 


网 站 地 图 框架 为 常见 情况 提供 了 一 个 便利 的 类 一 一 django.contrib.syndication.GenericSitemap。 


























使 用 这 个 类 创建 网 站 地 图 时 ， 要 传递 一 个 字典 ， 其 


wi FS 














此 外 ， 还 可 以 提供 date_field 键 ， 指 定 查 询 集合 





P 各 对 象 的 日 




















站 地 图 的 Lastmod 属性 。 





还 可 以 把 priority 和 changefreq 关键 字 参 数 传 给 GenericSitemap 构造 方法 ， 指 定 各 URL 的 对 应 属性 。 


示例 





下 述 示例 在 URL 配置 中 使 用 GenericSitemap 


from django.conf.urls import url 

from django.contrib.sitemaps import Generi 
from django.contrib.sitemaps.views import 
from blog.models import Entry 


Tnfo dVet = 二 
'queryset': Entry.objects.all(), 
'date_field': 'pub_date', 





cSitemap 
sitemap 


中 至 少 有 一 个 queryset 键 ， 
哪个 字段。 


期 使 




















于 生成 网 站 地 图 中 的 条 目 。 





























日 





期 字段 中 的 值 用 于 生成 网 
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urlpatterns = [ 
# 使 用 info_dict 的 通用 视图 
时 


# 网 站 地 图 

url(r'^sitemap\.xml$', sitemap, 
{'sitemaps': {'blog': GenericSitemap(info dict, priority=0.6)}}, 
name='django.contrib.sitemaps.views.sitemap'), 


14.7.7 静态 视图 的 网 站 地 图 





通常 ， 我 们 还 想 让 搜索 引擎 怜 虫 索引 对 象 详情 页 面 和 普通 页 面 之 外 的 视图 。 为 此 ， 要 在 items 中 列 出 视图 的 
URL 名 称 ， 然 后 在 网 站 地 图 的 Location 方法 中 调用 reverse()。 例 如 : 





























# sitemaps.py 
from django.contrib import sitemaps 
from django.core.urlresolvers import reverse 


class StaticViewSitemap(sitemaps.Sitemap): 
priority = 0.5 
changefreq = 'daily' 


def items(self): 
return ['main', 'about', 'license'] 


def location(self, itenm): 
return reverse(item) 


# urls.py 
from django.conf.urls import url 
from django.contrib.sitemaps.views import sitemap 


from .sitemaps import StaticViewSitemap 
from . import views 


sitemaps = { 
'static': StaticViewSitemap, 


urlpatterns = [ 
url(r'^$', views.main, name='main'), 
url(r'^about/$', views.about, name="'about'), 
url(r'^license/$', views.license, name='license'), 
Ws 
url(r'^sitemap\.xml$', sitemap, {'sitemaps': sitemaps}, 
name="'django.contrib.sitemaps.views.sitemap') 


14.7.8 创建 网 站 地 图 索引 




















网 站 地 图 框架 还 支持 创建 网 站 地 图 索引 ， 引 用 sitemaps 字典 中 针对 各 个 栏目 的 网 站 地 图 文件 。 这 种 方式 的 不 
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同 之 处 是 : 


。 要 在 URL 配置 中 使 用 两 个 视图 : django.contrib.sitemaps.views.index() 和 django.con- 


trib.sitemaps.views.sitemap()。 





。 django.contrib.sitemaps.views.sitemap() 视图 接受 一 个 section 关键 字 参 数 。 


对 上 述 示例 来 说 ， 相 应 的 URL 配置 如 下 : 


from django.contrib.sitemaps import views 


urlpatterns = [ 
url(r'^sitemap\.xml$', views.index, {'sitemaps': sitemaps}), 
url(r'^sitemap-(?P<section>.+)\.xml$', views.sitemap, 
{'sitemaps': sitemaps}), 


] 








这 样 配 置 之 后 会 自动 生成 一 个 sitemap.xml 文件 ， 引 用 sitemap-flatpages.xml 和 sitemap-blog.xml。 网 站 地 

















图 类 和 sitemaps 字典 无 需 修改 。 




















如 果 网 站 地 图 中 的 URL 超过 50,000 个 ， 应 该 创建 索引 文件 。 这 样 ，Django 能 自动 为 网 站 地 图 分 页 ， 而 且 在 



































索引 中 能 体现 出 来 。 如 果 不 是 直接 使 用 网 站 地 图 视图 ， 侈 如 包装 在 缓存 装饰 器 中 ， 必 须 为 网 站 地 




















名 ， 并 把 sitemap_urL_name 传 给 索引 视图 : 





from django.contrib.sitemaps import views as sitemaps_views 
from django.views.decorators.cache import cache_page 


urlpatterns = [ 
url(r'^sitemap\.xml$', 
cache_page(86400)(sitemaps_views.index), 
{'sitemaps': sitemaps, 'sitemap_url name': 'sitemaps'}), 
url(r'^sitemap-(?P<section>.+)\.xml$', 
cache_page(86400)(sitemaps_views.sitemap), 
{'sitemaps': sitemaps}, name='sitemaps'), 


14.7.9 自 定义 模板 


如 果 想 使 用 
: 





























Ne 


from django.contrib.sitemaps import views 


urlpatterns = [ 

url(r'^custom-sitemap\.xml$', views.index, { 
'sitemaps': sitemaps, 
'template name': 'custom sitemap.html' 

])， 

url(r'^custom-sitemap-(?P<section>.+)\.xml$', Vviews.sitemap, { 
'sitemaps': sitemaps, 
'template name': 'custom sitemap.html' 


])， 























| 


视图 命 











# 他 的 模板 生成 网 站 地 图 或 索引 ， 在 URL 配置 中 把 tempLate_name 参数 传 给 sitemap 和 index 视 
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14.7.10 上 下 文 变量 














索引 


sitemaps 变 


网 站 地 图 





自 定 义 index() 和 sitemap() 视图 的 模板 时 ， 可 以 使 用 下 述 上 下 文 变量 。 











量 的 值 是 一 个 列表 ， 包 含 各 个 网 站 地 图 的 绝对 URL。 














urlset 变量 的 值 是 一 个 列表 ， 包 含 应 该 出 现在 网 站 地 图 中 的 URL。 各 个 URL 都 具有 Sitemap 类 定义 的 属 


性 : 


。 changefreq 


。 item 


。 lastmod 


。 location 


。 priority 








各 个 URL 多 了 个 iten 属性， 这 么 做 为 了 更 加 方便 定制 模板 ， 例 如 针对 Google 
图 类 的 items() 方法 返回 的 条 目 具 有 publication_data 和 tags 字段 ， 那 么 可 以 像 下 面 这 样 生 成 兼容 Google 
的 网 站 地 图 : 





{% spaceless %} 


{% 


url in urlset %} 

url.location }} 

if url.lastmod %}{{ url.lastmod|date:"Y-m-d" }}{% endif %} 
if url.changefreq %}{{ url.changefreq }}{% endif %} 

if url.priority %}{{ url.priority }}{% endif %} 


if url.item.publication_ date %} 
{{ url.item.publication date|date:"Y-m-d" }} 


endif %} 


if url.item.tags %}{{ url.item.tags }}{% endif %} 


{% endfor %} 
{% endspaceless %} 


14.7.11 通知 Google 








网 站 地 图 有 变化 时 ， 你 可 能 想 通 知 Google， 让 它 重 新 索引 你 的 网 站 。 为 此 ， 网 站 地 医 











新 闻 的 网 站 地 图 。 假 设 网 站 地 




















django.contrib.syndication.ping_google() 


ping_google() 函数 有 个 可 选 的 参数 ， 其 值 为 网 站 地 














数 ，ping_google() 尝试 反 向 解析 URL 配置 ， 找 出 网 站 地 图 的 路 径 。 如 果 无 法 


ping_google() 抛 出 django.contrib.sitemaps.SitemapNotFound 异常 。 








可 以 在 模型 的 save() 方法 中 调用 ping_google() 函数 : 





| 
葡 
洽 
区 
准 
全 
区 
薪 











图 的 绝对 路 径 (如 '/sitemap.xml') 。 如 果 未 提供 这 个 参 











外 定 网 站 地 图 的 URL， 
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from django.contrib.sitemaps import ping_google 


class Entry(models.Model): 
i 
def save(self, force insert=False, force update=False): 
super(Entry, self).save(force_insert, force_update) 
Ery: 
ping_google() 
except Exception: 
# 简化 处 理 ， 因 为 可 能 出 现 多 种 与 HTTP 有 关 的 异常 
pass 


然而 ， 更 加 有 效 的 方式 是 在 cron 脚本 或 定时 任务 中 调用 ping_google() 函数 。 这 个 函数 会 向 Google 的 服务 器 
发 送 HITP 请 求 ， 因 此 你 可 能 不 想 每 次 执行 save() 的 过 程 中 都 有 网 络 开销 。 


使 用 manage.py 通知 Google 


在 项 目 中 添加 网 站 地 图 应 用 之 后 ， 还 可 以 使 用 管理 命令 ping_google 通知 Google: 





python manage.py ping_google [/sitemap.xml] 


先 在 Google 中 注册 


在 Google Webmaster Tools 中 注册 你 的 网 站 之 后 才能 使 用 ping_google 命令 。 


14.8 接 下 来 


我 们 将 继续 探索 Django 内 置 的 工具 ， 下 一 章 深入 讨论 Django 的 会 话 框架 。 
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第 15 章 Django 会 话 


























试想 一 下 ， 如 果 每 访问 网 站 中 的 一 个 页 面 都 要 重新 登录 ， 或 者 你 经 常 访问 的 网 站 忘记 了 你 的 设置 ， 每 次 访问 











都 要 重新 输入 ， 那 该 有 多 麻烦 。 























现今 ， 如 果 网 站 不 通过 某 种 方式 记 住 你 是 谁 ， 以 及 你 之 前 在 网 站 中 的 活动 情况 ， 失 去 的 是 可 











性 和 便利 性 。 














HTTP 本 身 是 无 状态 的 ， 两 次 请 求 之 间 没 有 连续 性 ， 服 务 器 无 法 知晓 后 续 请 求 是 不 是 来 自 
这 种 状态 上 的 缺失 由 会 话 (session) 弥补 。 会话 是 位 于 浏览 器 和 Web 服务 器 之 间 的 半 永 久 怕 


















































同 





个 人 。 








双向 通信 。 大 多 

















数 情况 下 ， 访 问 现代 的 网 站 时 ，Web 服务 器 会 使 用 匿名 会 话 记 录 与 访问 有 关 的 数据 。 这 种 会 话 之 所 以 是 匿名 





的 ， 原 因 在 于 Web 服务 器 只 能 记录 你 做 了 什么 ， 却 无 法 得 知 你 是 谁 。 











我 们 遇 到 过 这 种 情况 : 一 段 时 间 之 后 再 访问 电 商 网 站 ， 你 会 发 现 ， 虽 然 没 有 提供 个 人 信息 ， 但 是 以 前 放 在 购 
物 车 中 的 商品 还 在 。 会 话 经 常 使 用 名 声 不 好 且 很 少 被 人 理解 的 cookie 持久 存储 。 与 其 他 所 有 Web 框架 一 























样 ，Django 也 使 用 cookie， 但 是 你 会 发 现 ， 它 的 处 理 方式 更 灵巧 、 更 安全 。 












































Django 完全 支持 匿名 会 话 。 通 过 会 话 框 架 可 以 针对 网 站 的 每 个 访客 存储 和 检索 任意 的 数据 。Django 把 会 话 数 
据 存储 在 服务 器 端 ， 而 且 对 发 送 和 接收 cookie 的 过 程 做 了 抽象 。cookie 中 存储 的 是 会 话 ID ， 而 不 是 数据 本 身 















































(除非 使 用 基于 cookie 的 后 端 ) 一 一 这 样 实现 更 安全 。 














15.1 启用 会 话 




















会 话 由 一 个 中 间 件 实现 。django-admin startproject 命令 创建 的 settings.py 文件 默认 已 激活 SessionMid- 
dleware。 为 了 保证 会 话 可 用 ，MIDDLEWARE_CLASSES 设置 中 要 列 出 'django.contrib.sessions.middleware.Ses- 

















sionMiddLeware ' 。 





如 果 不 想 使 用 会 话 ， 可 以 把 MIDDLEWARE_CLASSES 中 的 SesstonMitddLeware 和 INSTALLED_APPS 中 的 'djan- 





go.contrib.sessions' 删 掉 。 这 样 能 节省 少量 的 开销 。 

















15.2 配置 会 话 引擎 











默认 情况 下 ，Django 在 数据 库 中 存储 会 话 (使 用 django.contrib.sessions.models.Session 模型 ) 。 这 样 虽 


























然 方便 ， 但 是 某 些 情况 下 在 别处 存储 数据 速度 更 快 ， 因 此 Django 允许 修改 配置 ， 把 会 话 数据 存储 在 文件 系统 





或 缓存 中 。 


15.2.1 使 用 基于 数据 库 的 会 话 








如 果 想 把 会 话 存储 在 数据 库 中 ， 要 在 INSTALLED_APPS 设置 中 添加 'django.contrib.sessions'。 然 后 ， 运 外 








manage.py migrate 命令 ， 创 建 存储 会 话 数据 的 数据 表 。 














15.2.2 使 用 基于 缓存 的 会 话 
































为 了 提升 性 能 ， 你 可 能 想 使 用 基于 缓存 的 会 话 后 端 。 使 用 Django 的 缓存 系统 存储 会 话 数 据 之 前 ， 要 先 配置 好 

















缓存 ， 详 情 参见 第 16 章 。 
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仅 当 使 用 Memcached 这 个 缓存 后 端 时 才 应 该 使 用 基于 缓存 的 会 话 。 本 地 内 存 缓存 后 端 留 存 数 
据 的 时 间 不 够 长 ， 不 是 个 好 选择 ， 此 外 ， 直 接 使 用 文件 或 数据 库存 储 会 话 ， 比 一 切 都 通过 文件 
或 数据 库 缓存 后 端 发 送 更 快 。 而 且 ， 本 地 内 存 缓存 后 端 对 多 进程 不 安全 ， 因 此 可 能 不 适合 在 生 
产 环境 中 使 用 。 





如 果 CACHES 设置 定义 了 多 个 缓存 后 端 ，Django 将 使 用 默认 的 那个 。 若 想 使 用 其 他 缓存 后 端 ， 把 SES- 
SION_CACHE_ALIAS 设 为 那个 后 端的 名 称 。 配 置 好 缓存 之 后 ， 在 缓存 中 存储 会 话 数据 有 两 种 方式 : 


1. 把 SESSION_ENGINE 设 为 "django.contrib.sessions.backends.cache"， 使 用 简单 的 缓存 会 话 存储 器 。 此 
时 ， 会 话 数据 直接 存储 在 缓存 中 。 然 而 ， 会 话 数据 可 能 无 法 持久 存储 ， 因 为 缓存 存储 器 空间 用 完 或 组 
存 服务 器 重启 后 数据 会 丢失 。 

2.， 若 想 持久 存储 缓存 的 会 话 数 据 ， 把 SESSION_ENGINE 设 为 "django.contrib.sessions.back- 
ends.cached_db"。 此 时 使 用 的 是 直 写 式 缓存 (write-through cache) ， 写 入 缓存 的 数据 也 会 写 入 数据 
库 。 如 果 缓 存 中 没有 会 话 数据 ， 再 到 数据 库 中 读 取 。 








这 两 种 会 话 存储 器 的 速度 都 十 分 快 ， 不 过 简单 缓存 更 快 ， 因 为 它 不 做 持久 存储 。 多 数 情 况 下 ，cached_db 后 
端 足 够 快 了 ， 然而， 如 果 你 还 需要 那 最 后 一 点 性 能 ， 而 且 想 随 着 时 间 的 推移 控 除 会 话 数 据 ， 可 以 使 用 cache 
后 端 。 如 果 使 用 cached_db 后 端 ， 还 要 按照 15.2.1 市 的 说 明 配 置 。 





15.2.3 使 用 基于 文件 的 会 话 





若 想 使 用 基于 文件 的 会 话 ， 把 SESSION_ENGINE 设 为 "django.contrib.sessions.backends.file"。 你 可 能 还 想 
配置 SESSION_FILE_PATH (默认 为 tempfile.gettempdir() 得 到 的 结果 ， 通 常 是 /tmp) ， 设 定 Django 存储 会 话 
文件 的 位 置 。 确 保 Web 服务 器 有 指定 位 置 的 读 写 权限 。 


15.2.4 使 用 基于 cookie 的 会 话 





若 想 使 用 基于 cookie 的 会 话 ， 把 SESSION_ENGINE 设 为 "django.contrib.sessions.backends.signed_cook- 
ies"。 会 话 数据 使 用 Django 的 签名 工具 和 SECRET_KEY 存储 。 





建议 别 动 SESSION_COOKIE_HTTPONLY 设置 ， 仍 然 使 用 True， 以 防 JavaScript 访问 存储 的 数据 。 


如 果 没 有 保护 好 SECRET_KEY， 而 且 使 用 的 是 Pickleserializer， 那 么 可 能 导致 远程 执行 任意 代 
码 。 


获得 SECRET_KEY 的 攻击 者 不 仅 可 以 自 改 会 话 数据 〈 能 通过 网 站 的 验证 ) ， 而 且 可 以 远程 执行 任 
意 代 码 ， 因 为 数据 是 使 用 pickle 序列 化 的 。 使 用 基于 cookie 的 会 话 时 一 定 要 多 加 小 心 ， 保 护 好 
密 钥 ， 不 让 任何 系统 远程 访问 。 
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会 话 数据 有 签名 ， 但 是 未 加 密 


cookie 后 端 中 的 会 话 数据 可 以 被 客户 端 读 取 。 为 了 防止 客户 端 修改 数据 ，cookie 使 用 

MAC (Message Authentication Code， 消 息 验证 码 ) 保护 ， 因 此 ， 一旦 被 算 改 ,会话 数据 即行 
失效 。 如 果 cookie 无 法 存储 全 部 会 话 数据 ， 有 数据 丢失 ， 会 话 也 失效 。 虽 然 Django 会 压缩 数 
据 ， 但 是 也 完全 有 可 能 超出 cookie 的 4096 字 节 限制 。 


无 法 保证 新 鲜 


还 要 注意 ， 虽 然 MAC 可 以 保证 数据 的 真 伪 ( 即 由 你 的 网 站 生成 ， 而 不 是 别人 生成 的 ) 、 数 据 
的 完整 性 ( 即 数据 都 在 ， 而 且 正 确 ) ,但 是 无 法 保障 数据 是 新 鲜 的 ， 即 发 回 的 数据 与 发 送 给 客 
户 端的 一 样 。 这 意味 着 ， 某 些 情况 下 cookie 后 端 中 的 会 话 数据 可 能 导致 重 放 攻 击 (replay at- 
tack) 。 有 些 会 话 后 端 会 在 服务 器 端 记录 各 个 会 话 ， 并 在 用 户 退 出 后 让 会 话 失 效 ， 但 是 基于 
cookie 的 会 话 则 不 然 。 因 此 ， 攻 击 者 咨 取 用 户 的 cookie 后 ， 即 使 用 户 已 经 退出 ， 也 能 以 那个 用 
户 的 身份 登录 。 仅 当 cookie 的 存在 时 间 比 SESSION_COOKIE_AGE 设 定 的 值 长 时 才 会 被 识别 为 “过 











最 后 要 说 的 是 ， 如 果 上 述 警 告 还 没有 让 你 放弃 使 用 基于 cookie 的 会 话 ， 那 么 再 看 这 一 点 : cookie 的 大 小 可 能 
会 对 网 站 的 速度 有 影响 。 





15.3 在 视图 中 使 用 会 话 





激活 SessionMiddleware 之 后 ， 每 个 HttpRequest 对 象 ( 传 给 任何 Django 视图 函数 的 第 一 个 参数 ) 都 有 一 个 
session 属性 ， 其 值 是 一 个 类 似 字 典 的 对 象 。 在 视图 中 ， 任 何 时 候 都 可 以 读 写 request.session， 其 至 可 以 多 
次 编辑 。 


会 话 对 象 继 承 自 基 类 backends .base.SessionBase， 具 有 下 述 标准 的 字典 方法 : 























。 __getitem (key) 
。 _ setitem (key, value) 


。 _ delitem (key) 


__Ccontains__(key) 


get(key, default=None) 


pop(key) 
keys() 


。 items() 


。 setdefault() 


。 clear() 


此 外 ， 还 有 下 述 方法 。 


15.3.1 flush() 





从 会 话 中 删除 当前 会 话 数据 ， 并 把 会 话 cookie 删除 。 如 果 想 确保 用 户 的 浏览 器 不 能 再 访问 之 前 的 会 话 数据 
(例如 django.contrib.auth.Logout() 函数 会 调用 它 ) ， 可 以 调用 这 个 方法 。 
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15.3.2 set_test_cookie() 











设 定 一 个 测试 cookie， 确认 用 户 的 浏览 器 是 否 支 持 cookie。 由 于 cookie 运作 方式 上 的 限制 ， 只 能 等 到 用 户 下 
一 次 请 求 页 面 时 才能 做 这 项 测试 。 详 情 参 见 15.6 节 。 














15.3.3 test_cookie_worked() 














根据 用 户 的 浏览 器 是 否 接 受 测试 cookie 返回 True 或 FaLse。 由 于 cookie 运作 方式 上 的 限制 ， 要 在 之 前 的 单独 
页 面 请 求 中 调用 set_test_cookie()。 详 情 参见 15.6 节 。 














15.3.4 delete test cookie() 


删除 测试 cookie。 测 试 完 用 于 清理 。 

















15.3.5 set_ expiry(value) 


设 定 会 话 的 过 期 时 间 。 可 以 传人 的 值 有 : 














。 把 value 设 为 整数 时 ， 会 话 在 指定 的 秒 数 后 过 期 。 例 如 ，request.session.set_expiry(300) 的 意思 是 
会 话 在 5 分 钟 后 过 期 。 


。 把 value 设 为 datetime 或 timedelta 对 象 时 ， 会 话 在 指定 的 日 期 (时间) 过 期 。 注 意 ， 仅 当 使 用 
pickleSerializer 时 datetime 和 timedelta 对 象 才 可 以 序列 化 。 


。 把 value 设 为 9 时， 用 户 的 会 话 cookie 在 Web 浏览 器 关闭 后 过 期 。 
。 把 value 设 为 None 时 ,使 用 全 局 的 会 话 过 期 策略 。 






















































































读 取 会 话 不 会 延长 过 期 时 间 。 会 话 过 期 的 依据 是 最 后 的 修改 时 间 。 


15.3.6 get_ expiry_age() 


l 


水 





返回 会 话 还 有 多 少 秒 过 期 。 对 未 自 定义 过 期 时 间 (或 者 在 浏览 器 关闭 时 过 期 ) 的 会 话 来 说 ， 返 回 的 值 等 于 
SESSION_COOKIE_AGE。 这 个 方法 接受 两 个 可 选 的 关键 字 参 数 : 

















。 modification: 一 个 datetime 对 象 ， 会 话 的 最 后 修改 时 间 。 默 认为 当前 时 间 。 


。 expiry: 表示 会 话 过 期 信息 的 datetime 对 象 、 整 数 ( 秒 数 ) 或 None。 如 果 调 用 set_expiry() 设 定 了 过 
期 信息 ， 默 认 就 是 那个 值 ， 否 则 是 None。 





























15.3.7 get_expiry_date() 











水 








返回 会 话 过 期 的 日 期 。 对 未 自 定义 过 期 时 间 (或 者 在 浏览 器 关闭 时 过 期 ) 的 会 话 来 说 ， 返 回 SESSION_COOK- 
IE_AGE 的 值 距 现在 的 秒 数 。 这 个 方法 也 接受 get_expiry_age() 方法 的 那 两 个 关键 字 参 数 。 




















15.3.8 get_ expire at browser_close() 

















根据 用 户 的 会 话 cookie 是 否 在 Web 浏览 器 关闭 后 过 期 ， 返回 True 或 False。 


15.3.9 clear_expired() 





从 会 话 存 储 器 中 移 除 过 期 的 会 话 。clearsessions 命令 会 调用 这 个 类 方法 。 
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15.3. 


创建 一 个 新 的 会 


固定 


15.4 


。 别 使 用 新 对 象 覆 盖 request.session， 


15.5 


在 1.6 


后 端 ， 而 且 攻 击 者 知道 了 SECRET_KEY (Django 没有 
入 字符 串 ， 反 序列 化 会 


存储 的 是 签名 后 的 会 话 





话 中 提 


虽然 为 了 防止 算 改 ，cookie 
就 凸显 出 来 了 。 把 序列 化 会 
1.5.3 引入 了 一 个 新 设置 ， 即 SESSION_SERIALIZER， 用 于 自 


1.5.x 
1.6 之 





10 cycle_key() 


话 键 ， 但 是 保 外 


(session fixation) 攻击 。 





会 话 对 象 指导 方针 











request.session 字 








会 话 序列 化 


当前 


1 的 会 


可 











如 的 ， 供 Django 内 部 使 用 。 
也 别 访问 或 六 














版 之 前 ，Django 默认 使 























后 默认 使 用 




















cookie 后 端 时 。 


15.5. 











1 内 置 的 序列 化 程序 


serializers.JSONSerializer 


django.core.signing 提供 的 JSON 序列 化 程序 包装 。 只 外 
因此 不 能 在 request.session 中 使 用 非 字 符 串 键 ， 


串 键 ， 





>>> # 初始 赋值 
>>> request.session[0] = 'bar' 


>>> # 后 续 请 求 要 序列 化 和 反 序 列 化 会 


>>> request.session[0] 


话 数据 的 方式 








pickle 序列 化 会 











话 后 在 服务 器 中 执行 
































话 数据 ， 然 后 再 存 人 后 端 。 如 果 使 
内 在 的 漏洞 会 导致 这 个 密 钥 泄露 ) 
E 意 的 代码 。 网 上 充斥 着 这 种 简 而 


数据 ， 可 是 一 旦 SECRET_KEY 泄露 ， 远 程 执行 代码 的 漏洞 
1 pickle 改 成 JSON 可 以 降低 这 种 攻击 的 可 行 性 。 为 此 ，Django 

















定义 会 话 


默认 使 用 django.contrib.sessions.serializers.PickleSerializer; 


话 数 据 。django.contrib.auth.login() 会 调用 这 个 方法 ， 


以 防 会 话 


中 的 键 使 用 普通 的 Python 字符 串 。 这 不 是 不 得 违反 的 规则 ， 而 是 一 种 约定 。 
以 下 划 线 开头 的 键 是 保留 




















设 定 它 的 属性 。 像 Python 字 


那样 使 用 它 。 


























的 是 签名 的 cookie 会 话 





， 那 么 攻击 者 可 以 在 会 

















易 行 的 技术 。 




















django.contrib.sessions.seriaLizers.JSONSeriaLizer。 


的 序列 化 格式 。 为 了 向 
但 是 ， 为 了 增强 安全 | 


后 兼容 ，Django 
了 性，Dijango 

















话 数据 
# KeyError 


>>> request.session['0'] 


'bar' 


JSON 序列 化 的 不 足 之 处 参见 15.5.2 节 。 


serializers.PickleSerializer 


支持 序列 化 任何 Python 对 象 ， 但 是 如 前 所 述 ， 如 果 攻 击 者 得 知 了 SECRET_KEY， 


15.5. 


\ 芝 
诈 意 
,区 、， 


间 ， 我 们 需 


2 自己 编写 序列 化 程序 


与 PickleSerializer 不 同 ，JSONSeriaLizer 无 法 处 理 所 
如 果 想 在 JSON 序列 化 的 会 话 





要 取 合 。 














虽然 15.5.2 方 将 指出 JSON 序列 化 的 一 些 不 足 ， 但 是 我 们 还 是 强烈 推荐 始终 使 


存储 复杂 的 数据 类 型 ， 























序列 化 基本 的 数据 类 型 。 此 外 ，JSON 只 




















JSON 序列 化 ， 尤 其 是 使 用 





支持 字符 





程 代 码 执 行 漏洞 。 











了 Python 数据 类 型 。 通 常 ， 在 便利 和 安全 之 
例如 datetime 和 Decimal， 需 要 








15.4 会 话 对 象 指导 
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自己 编写 序列 化 程序 (或 者 在 存 人 request.session 之 前 把 复杂 的 值 转换 成 JSON 能 序列 化 的 对 象 ) 。 





虽然 序列 化 复杂 的 值 很 简单 (django.core.serializers.json.DateTimeAwareJSONEncoder 可 以 助 你 一 臂 之 
力 ) ,但 是 解码 时 车 想得到 与 序列 化 之 前 完全 一 样 的 值 并 非 易 事 。 例 如 ， 可 能 会 把 碰巧 与 日 期 格式 一 样 的 字 
符 串 变 成 datetime 对 象 。 






































自 定义 的 序列 化 程序 类 必须 实现 两 个 方法 : dumps(self，obj) 和 Loads(seLf，data)。 它 们 分 别 用 于 序列 化 和 
反 序 列 化 会 话 数据 字典 。 




















15.6 设 定 测 试 cookie 

















为 了 便于 测试 用 户 的 浏览 需 是 否 支 持 cookie，Django 提供 了 一 种 简单 的 方式 ， 只 需 在 一 个 视图 中 调用 re- 
quest.session 的 set_test_cookie() 方法 ， 然 后 在 后 续 视 图 (与 前 一 个 不 同 ) 中 调用 test_cookie_worked() 
方法 。 















































把 set_test_cookie() 和 test_cookie_worked() 分 开 看 似 不 便 ， 但 却 是 必要 的 ， 因 为 cookie 就 是 这 样 运作 
的 。 设 定 cookie 后 无 法 立即 判断 浏览 器 是 否 能 接受 ， 要 等 到 下 一 次 请 求 才 能 确定 。 测 试 完 之 后 ， 最 好 调用 
delete_test_cookie() 方法 清理 一 下 。 
































下 面 是 常见 的 做 法 举例 : 


def login(request): 
if request.method == 'POST': 
if request.session.test cookie worked(): 
request.session.delete_ test_cookie() 
return HttpResponse("You're logged in.") 
else: 
return HttpResponse("Please enable cookies and try again.") 
request.session.set_ test_cookie() 
return render_to_response('foo/login form.html') 


15.7 在 视图 之 外 使 用 会 话 











本 节 的 示例 直接 从 django.contrib.sessions.backends.db 后 端 导 人 Sessionstore 对 象 。 实 际 使 用 中 ， 应 该 像 
下 面 这 样 从 SESSION_ENGINE 设 定 的 会 话 引擎 中 导入 SessionStore: 

















>>> from importlib import import_module 
>>> from django.conf import settings 
>>> SessionStore = import module(settings.SESSION ENGINE).SessionStore 


在 视图 之 外 处 理会 话 数据 也 有 API: 





>>> from django.contrib.sessions.backends.db import SessionStore 
>>> s = SessionStore() 

>>> # 存储 距 Unix 纪元 的 秒 数 ， 因 为 datetime 对 象 不 能 序列 化 成 JSON 
>>> s['last_login'] = 1376587691 

>>> s.save() 

>>> s.session_key 

"2b1189a188b44ad18c35e113ac6ceead ' 


>>> s = SessionStore(session_key='2b1189a188b44ad18c35e113ac6ceead ' ) 
>>> S['Last_Login '] 
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1376587691 








为 了 规避 会 话 固定 攻击 ， 不 存在 的 会 话 键 会 重新 生成 : 








>>> from django.contrib.sessions.backends.db import SessionStore 
>>> s = SessionStore(session key='no-such-session-here') 

>>> s.save(l) 

>>> s.session_key 

"ff882814010ccbc3c870523934fee5a2 








对 django.contrib.sessions.backends.db 后 端 来 说 ， 各 个 会 话 就 是 普通 的 Django 模型 。Session 模型 在 
django/contrib/sessions/models.py 中 定义 。 鉴 于 此 ， 我 们 可 以 使 用 常规 的 Django 数据 库 API 访问 会 话 : 





>>> from django.contrib.sessions.models import Session 

>>> s = Session.objects.get(pk='2b1189a188b44ad18c35e113ac6ceead ' ) 
>>> s.expire_date 

datetime.datetime(2005, 8, 20, 13, 35, 12) 


























注意 ， 要 调用 get_decoded() 获取 会 话 字典 。 之 所 以 要 多 这 一 步 ， 是 因为 会 话 字 典 是 以 编码 后 的 格式 存储 
的 : 











>>> s.session_data 
'KGRWMQpTJ19hdXRoX3VzZXJfaWQnCnAyCkkxCnMuMTExY2ZjODI2Yj...' 
>>> s.get_ decoded() 

{'user_id': 42} 
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默认 情况 下 ， 仅 当 修 改 会 话 后 才 会 将 其 存 人 会话 数 据 库 。 这 里 说 的 “修改 "是 指 会 话 字典 中 的 值 有 增删 : 

















# 修改 了 会 话 
request.session['foo'] = 'bar 


# 修改 了 会 话 
del request.session['foo'] 


# 修改 了 会 话 
request.session['foo'] = {} 


# 小 心 : 没有 修改 会 话 ， 因 为 修改 的 是 request.session['foo'] 而 不 是 request.session 
request.session[ 'foo']['bar'] = 'baz' 























对 上 例 的 最 后 一 步 来 说 ， 可 以 设 定 会 话 对 象 的 modified 属性 ， 明 确 表明 修改 了 会 话 : 














request.session.modified = True 





若 想 修改 这 样 的 默认 行为 ， 把 SESSION_SAVE_EVERY_REQUEST 设 为 True。 此 时 ， 每 次 请 求 时 Django 都 会 把 会 话 
存 人 人 数据库。 注意 ， 只 有 创建 或 修改 了 会 话 才 会 发 送 会 话 cookie。 如 果 把 SESSION_SAVE_EVERY_REQUEST 设 为 
True， 每 次 请 求 都 会 发 送 会 话 cookie。 类 似 地 ， 每 次 发 送 会 话 cookie 都 会 更 新 expires 部 分 。 如 果 响 应 的 状 
态 码 是 500， 不 会 保存 会 话 。 
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15.9 持续 到 浏览 器 关闭 的 会 话 与 持久 会 话 


可 以 使 用 SESSION_EXPIRE_AT_BROWSER_CLOSE 设置 控制 会 话 框架 使 用 持续 到 浏览 器 关闭 的 会 话 还 是 持久 会 话 。 
SESSION_EXPIRE_AT_BROWSER_CLOSE 的 默认 值 是 FaLse， 这 意味 着 会 话 cookie 在 用 户 的 浏览 器 中 存储 的 时 间 等 
于 SESSION_COOKIE_AGE。 如 果 不 想 让 用 户 每 次 打开 浏览 器 后 都 重新 登录 ， 使 用 这 个 默认 值 。 























如 果 把 SESSION_EXPIRE_AT_BRONSER_CLOSE 设 为 True，Django 将 使 用 持续 到 浏览 器 关闭 的 会 话 ， 即 用 户 关 闭 
浏览 器 后 会 话 cookie 即 告 过 期 。 


有 些 浏览 器 (例如 Chrome) 提供 了 这 样 的 设置 ， 允 许 用 户 重新 打开 浏览 器 后 继续 使 用 会 话 。 
某 些 情况 下 ， 这 种 行为 与 SESSION_EXPIRE_AT_BROWSER_CLOSE 设置 相抵 ， 浏 览 器 关闭 后 会 话 不 过 
期 。 测 试 启用 了 SESSION_EXPIRE_AT_BRONSER_CLOSE 的 Django 应 用 时 要 注意 。 


15.10 清理 会 话 存 储 器 


用 户 创 建 的 会 话 不 断 积累 ， 占 据 着 会 话 存储 器 。Django 没有 提供 自动 清除 过 期 会 话 的 机 制 ， 因 此 你 自己 要 定 
期 清除 过 期 会 话 。 为 此 ，Django 提供 了 一 个 清理 命令 :clearsessions。 建 议 你 定期 执行 这 个 命令 ， 比 如 说 定 
义 一 个 每 天 执行 的 cron 作业 。 


注意 ， 缓 存 后 端 不 受 这 个 问题 的 影响 ， 因 为 缓存 会 自动 删除 过 期 的 数据 。cookie 亦 然 ， 因 为 会 话 数据 由 用 户 
的 浏览 器 存储 。 











15.11 接 下 来 


接 下 来 继续 探讨 高 级 的 Django 话题 ， 这 一 次 要 探讨 的 是 Django 的 缓存 后 端 。 
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动态 网 站 的 不 足 之 处 体现 在 "动态 "上 。 每 请 求 一 个 页 面 ，Web 服务 器 都 要 做 各 种 计算 ,为 了 让 访客 看 到 页 
面 ， 要 查询 数据 库 、 泻 染 模板 ， 还 要 执行 一 些 业务 逻辑 。 从 消耗 方面 来 看 ， 这 个 过 程 比 从 文件 系统 中 读 取 一 
个 文件 要 耗资 源 。 

对 多 数 Web 应 用 程序 来 说 ， 这 个 过 程 消 耗 的 资源 其 实 并 不 多 。 没 有 几 个 网 站 能 有 华盛顿 邮 报 网 站 或 Slashdot 


那样 的 体 量 ， 多 数 网 站 是 中 小 型 的 ， 流 量 水 平一 般 。 但 是 对 中 高 流量 水 平 的 网 站 来 说 ， 一 定 要 从 根本 上 尽量 
降低 消耗 。 









































































































































缓存 就 是 为 之 而 生 的 。 存 和 人 缓存 是 指 把 耗资 源 的 计算 结果 保存 起 来 ， 不 用 每 次 都 重新 计算 。 下 面 是 一 段 伪 代 
码 ， 说 明 缓存 在 动态 生成 网 页 的 过 程 中 所 起 的 作用 : 




















given a URL, try finding that page in the cache if the page is in the cache: 
return the cached page 
else: 
generate the page 
save the generated page in the cache (for next time) 
return the generated page 














Django 提供 了 一 个 强健 的 缓存 系统 ， 能 把 动态 页 面 保存 起 来 ， 不 用 每 次 请 求 都 重新 生成 。 为 了 便于 使 用 ， 
Django 提供 的 缓存 分 为 不 同 的 粒度 层次 ， 可 以 缓存 特定 视图 的 输出 、 可 以 只 缓存 不 易 生成 的 片段 ， 也 可 以 组 
存 整个 网 站 。 



























































Django 还 能 很 好 地 支持 下 游 缓存 ， 例 如 Squid 和 基于 浏览 器 的 缓存 。 这 两 种 缓存 不 直接 受 你 控制 ， 但 是 你 可 
以 给 出 提示 (通过 HTTP 首部 ) ， 指 明 网 站 的 哪些 部 分 要 缓存 ， 以 及 如 何 缓存 。 








16.1 配置 缓存 


























缓存 系统 要 少许 配置 之 后 才能 使 用 。 有 具体 而 言 ， 你 要 指明 缓存 的 数据 存储 在 哪里 ， 在 数据 库 中 、 文 件 系统 
中 ， 还 是 直接 放 在 内 存 中 。 这 是 一 项 重要 决策 ， 影 响 着 缓存 的 性 能 。 























缓存 在 设置 文件 中 的 CACHES 设置 项 目 中 配置 。 











16.1.1 Memcached 











Django 原生 支持 的 速度 最 快 的 ， 也 是 效率 最 高 的 缓存 是 Memcached。 这 是 一 个 完全 基于 内 存 的 缓存 服务 器 ， 
由 Danga Interactive 公司 开发 ， 最 初 的 目的 是 处 理 LiveJournal.com 的 高 负载 ， 而 后 开源 了 。Facebook 和 
Wikipedia 等 网 站 使 用 它 减 少数 据 库 访问 ， 大 幅 提 升 网 站 的 性 能 。 


Memcached 以 守护 进程 的 方式 运行 ， 需 要 专门 分 配 一 定量 的 RAM。 它 的 作用 很 简单 ， 就 是 为 增加 、 读 取 和 
删除 缓存 中 的 数据 提供 高 速 接口 。 所 有 数据 都 直接 存储 在 内 存 中 ， 因 此 对 数据 库 或 文件 系统 没有 消耗 。 






























































安装 完 Memcached 之 后 ， 还 要 安装 一 个 Memcached 绑 定 。Python 的 Memcached 绑 定 有 好 几 个 ， 其 中 
python-memcached 和 python-memcached 是 最 常用 的 。 在 Django 中 使 用 Memcached 的 步 又 如 下 : 



































。 把 BACKEND 设 为 django.core.cache.backends.memcached.MemcachedCache 或 django.core.cache.back- 





237 


ends .memcached.PyLibMCCache (根据 你 所 选 的 Memcached 绑 定 而 定 ) 。 


。 把 LOCATION 设 为 ip:port 这 种 形式 的 值 ， 其 中 ip 是 Memcached 守护 进程 的 卫 地 址 ，port 是 运行 
Memcached 的 端口 ， 或 者 设 为 unix:path 这 种 形式 的 值 ， 其 中 path 是 Memcached 的 Unix 套 接 字 文 件 
的 路 径 。 























在 下 述 示 例 中 ，Memcached 运行 在 本 地 (127.0.0.1) 的 11211 端口 上 ,使 用 的 是 python-memcached 绑 定 : 











CACHES = { 
'default': { 
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache ' ， 
DCATION "127:0:01411211", 


} 





在 下 述 示例 中 ，Memcached 通过 一 个 本 地 的 Unix 套 接 字 文 件 〈/tmp/memcached.sock) 访问 ， 使 用 的 是 
python-memcached 绑 定 : 


CACHES = { 
'default': { 
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', 
'LOCATION': 'unix:/tmp/memcached.sock', 


} 


Memcached 有 个 极 好 的 特性 ， 支持 多 个 服务 器 共享 同一 个 缓存 。 这 意味 着 ， 可 以 在 多 台 设 备 中 运行 多 个 
Memcached 守护 进程 ， 而 程序 把 这 一 组 设备 视 作 一 个 缓存 ， 因 此 无 需 在 每 台 设备 中 重复 缓存 值 。 若 想 使 用 
个 特性 ， 在 LOCATION 中 列 出 全 部 服务 器 的 地 址 ， 使 用 分 号 分 隔 ， 或 者 以 列表 指定 。 






































沟 





























在 下 述 示例 中 ， 缓 存在 172.19.26.240 和 172.19.26.242 两 个 IP 地 址 (端口 都 是 11211) 对 应 的 设备 中 运行 的 
Memcached 实例 之 间 共 享 : 





CACHES = { 
'default': { 
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache ' ， 
'LOCATION' : [ 
"219 26 990 
2 119626.242:11211!. 
] 
} 
} 


在 下 述 示 例 中 ， 组 存在 172.19.26.240 (11211 端口 ) 、172.19.26.242 (11212 端口 ) 和 
172.19.26.244 (11213 端口 ) 三 个 卫 地 址 对 应 的 设备 中 运行 的 Memcached 实例 之 间 共 享 : 




















CACHES = { 
'default': { 
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache ' ， 
'LOCATION' : [ 
“219 26, 2405 42 
9 26 441242. 
"T7219 26, 244511243.", 
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} 


最 后 要 指出 的 是 ，Memcached 这 种 基于 内 存 的 缓存 有 个 缺点 : 因为 缓存 的 数据 存储 在 内 存 中 ， 所 以 服务 器 一 
且 骨 省， 数据 就 不 复 存 在 了 。 


显然 ， 内 存 的 目的 不 是 永久 存储 数据 ， 因 此 别 把 基于 内 存 的 缓存 当做 唯一 的 存储 器 。 弓 良 置 疑 ，Django 支持 
的 所 有 缓存 后 端 都 不 应 该 用 于 永久 存储 ， 它 们 的 唯一 目的 是 缓存 ， 而 不 是 存储 。 之 所 以 在 这 里 特别 指出 ， 是 
因为 基于 内 存 的 缓存 更 是 临时 的 。 
















































































16.1.2 数据 库 缓存 


Django 可 以 把 缓存 数据 存 人 数据 库 。 如 果 数 据 库 服务 器 的 索引 稳定 快速 ， 这 样 做 效果 最 好 。 以 数据 表 为 缓存 
后 端的 步骤 如 下 : 








。 把 BACKEND 设 为 django.core.cache.backends.db.DatabaseCache。 


。 把 LOCATION 设 为 数据 表 的 名 称 。 这 个 数据 表 的 名 称 随意 起 ， 只 要 是 有 效 的 表 名 ， 而 且 没 被 数据 库 占 
用 。 























在 下 述 示例 中 ， 缓 存 表 的 名 称 是 my_cache_table: 


CACHES = { 
'default': { 
'BACKEND': 'django.core.cache.backends.db.DatabaseCache ' ， 
"LOCATION ' : 'my_cache_ table', 


} 
创建 缓存 表 
使 用 数据 库 缓存 之 前 ， 必 须 执行 下 述 命令 创建 缓存 表 : 





python manage.py createcachetable 








这 个 命令 使 用 Django 的 数据 库 缓 存 系统 所 期 待 的 格式 在 数据 库 中 创建 一 个 表 。 表 名 从 LOCATION 中 获取 。 如 
果 使 用 多 个 数据 库 缓 存 ，createcachetable 命令 会 分 别 为 各 个 缓存 创建 一 个 表 。 如 果 使 用 多 个 数据 库 ，cre- 
atecachetable 命令 会 观察 数据 库 路 由 的 allow_migrate() 方法 (参见 下 文 ) 。 与 migrate 一 样 ，createca- 
chetable 命令 不 会 触 磁 现 有 的 表 ， 而 只 是 创建 缺失 的 表 。 





























多 个 数据 库 








如 果 把 缓存 存 人 多 个 数据 库 ， 还 要 为 缓存 表 提 供 路 由 指令 。 为 此 ， 缓 存 表 对 应 的 模型 名 为 CacheEntry， 位 于 
名 为 django_cache 的 应 用 中 。 这 个 模型 不 出 现在 模型 缓存 中 ， 它 的 作用 是 提供 详细 的 路 由 信息 。 


例如 ， 下 述 路 由 把 读 缓存 操作 交 给 cache_replica 数据 库 处 理 ， 把 写 缓 存 操 作 交 给 cache_primary 数据 库 处 
理 ， 而 且 缓存 表 只 向 cache_primary 中 同步 : 


















































class CacheRouter(object): 
"""A router to control all database cache operations""" 


def db_for_read(self, model, **hints): 
# 缓存 从 这 个 副本 中 读 取 
if modeL._meta.app_LabeL in ('django_cache',): 
return 'cache_replica' 
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return None 


def db for write(self, model, **hints): 
# 缓存 写 入 这 个 主 缓存 
if model. meta.app_label in ('django_cache',): 
return 'cache_primary' 
return None 


def allow migrate(self, db, model): 
# 只 在 主 缓存 中 安装 缓存 模型 
if model. meta.app_label in ('django_cache',): 
return db == 'cache_primary' 
return None 








如 果 不 为 数据 库 缓存 模型 指定 路 由 方向 ， 缓 存 后 端 将 使 用 defautt 数据 库 。 当 然 ， 如 果 你 不 使 用 数据 库 缓存 
后 端 ， 就 无 需 费心 为 数据 库 缓存 模型 提供 路 由 指令 。 





16.1.3 文件 系统 缓存 


基于 文件 的 后 端 会 序列 化 各 个 缓存 的 值 ， 将 其 存 人 单独 的 文件 。 若 想 使 用 这 个 后 端 ， 把 BACKEND 设 为 'djan- 
go.core.cache.backends.filebased.FileBasedCache' ， 并 把 LOCATION 设 为 合适 的 目录 。 


























假如 想 把 缓存 的 数据 存储 在 /var/tmp/django_cache 目录 中 ， 使 用 下 述 设置 





CACHES = { 
'default': { 
'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache', 
'LOCATION': '/var/tmp/django_cache', 


} 
使 用 Windows 时 ， 要 在 路 径 的 开头 加 上 盘 符 ， 例 如 : 


CACHES = { 
'default': { 
'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache', 
"LOCATION "es/foo/bar”, 


} 


目录 的 路 径 应 该 是 绝对 的 ， 即 应 该 从 文件 系统 的 根 开始 。 路 径 末 尾 有 没有 和 斜 线 没有 关系 。 确 保 LOCATION 指向 
的 目录 存在 ， 而 且 运行 Web 服务 器 的 用 户 有 读 写 权限 。 以 上 例 为 例 ， 如 果 运 行 服务 器 的 用 户 是 apache， 那 么 
要 确保 /var/tmp/django_cache 目录 存在 ， 而 且 apache 用 户 有 读 写 权限 。 






























































16.1.4 本 地 内 存 缓存 


如 果 没 在 设置 文件 中 配置 ， 默 认 使 用 这 个 缓存 。 如 果 想 要 内 存 缓存 的 速度 优势 ， 但 是 无 法 使 用 Memcached ， 
可 以 考虑 使 用 本 地 内 存 缓存 后 端 。 和 车 想 使 用 它 ， 把 BACKEND 设 为 django.core.cache.backends.Locmem.LocMem- 
Cache。 例 如 : 
































CACHES = { 
'default': { 
'BACKEND': 'django.core.cache.backends.Locmem.LocMemCache ' ， 
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"LOCATION ' : "unique-snowfLake' 


} 


LOCATION 用 于 标识 各 个 内 存 存 储 器 。 如 果 只 有 一 个 本 地 内 存 缓存 ， 可 以 不 设 LOCATION; 然而， 如 果 有 多 个 ， 
至 少 要 为 其 中 一 个 命名 ， 以 示 区 分 。 


注意 ， 每 个 进程 都 有 各 自私 有 的 缓存 实例 。 这 意味 着 ， 缓 存 不 能 跨 进程 。 这 也 意味 着 ， 本 地 内 存 缓存 对 内 存 
的 利用 效率 并 不 高 ， 因 此 可 能 不 适合 在 生产 环境 使 用 。 在 开发 环境 中 用 着 还 是 不 错 的 。 




















16.1.5 虚拟 缓存 ( 供 开发 ) 


最 后 ，Django 还 提供 了 一 个 虚拟 缓存 ， 它 并 不 真正 缓存 ， 只 是 实现 了 缓存 接口 。 如 果 生 产 环境 大 量 使 用 绥 
存 ， 而 在 开发 和 测试 环境 中 不 想 使 用 缓存 ， 又 不 想 改 代 码 ， 就 可 以 使 用 这 个 后 端 。 启 用 虚拟 缓存 的 方式 是 像 
这 样 设置 BACKEND: 






































CACHES = { 
'default': { 
'BACKEND': 'django.core.cache.backends.dummy .DummyCache', 
} 
} 


16.1.6 使 用 自 定义 的 缓存 后 端 


尽管 Django 原生 支持 多 个 缓存 后 端 ， 但 有 时 候 你 可 能 想 使 用 自 定义 的 后 端 。 此 时 ， 要 把 CACHES 设置 的 BACK- 
END 选项 设 为 外 部 缓存 后 端的 Python 导入 路 径 : 


CACHES = { 
'default': { 
'BACKEND': 'path.to.backend', 
} 
} 
自 定义 缓存 后 端 时 ， 可 以 参照 标准 的 后 端 。 相 关 的 源码 在 django/core/cache/backends/ 目录 中 。 





除非 迫不得已 ， 例 如 主机 不 支持 ， 和 否则 应 该 始终 使 用 Django 自 带 的 缓存 后 端 。 内 置 的 后 端 有 
良好 的 测试 ， 而 且 易 于 使 用 。 























16.1.7 缓存 的 参数 


每 个 缓存 后 端 都 可 以 指定 额外 的 参数 ， 用 于 控制 缓存 的 行为 。 额 外 的 参数 通过 CACHES 设置 中 额外 的 键 指定 。 
可 用 的 参数 有 : 





。 TIMEOUT: 缓存 默认 的 超时 时 间 ( 秒 数 ) 。 默 认 值 为 300 秒 (5 分 钟 ) 。 可 以 设 为 None， 即 缓存 键 永 不 
过 期 。 设 为 6 时， 缓存 键 立即 过 期 (相当 于 没 缓存 ) 。 


。 OPTIONS: 传 给 缓存 后 端的 选项 。 每 个 后 端 可 用 的 选项 有 所 不 同 。 以 第 三 方 库 为 支持 的 缓存 后 端 会 把 选 
项 直接 传 给 底层 的 缓存 库 。 


。 实现 剔除 策略 的 缓存 后 端 〈 即 本 地 内 存 后 端 、 文 件 系统 后 端 和 数据 库 后 端 ) 接受 下 述 选 项 : 








16.1 配置 缓存 - 241 








。 MAX_ENTRIES: 删除 旧 值 之 前 允许 存储 的 条 目 最 大 数 。 默 认 值 为 300。 

。 CULL_FREQUENCY: 达到 MAX_ENTRIES 设 定 的 上 限时 剔除 的 条 目 比 例 。 真 正 的 比例 其 实 是 1 / 
CULL_FREQUENCY， 因 此 把 CULL_FREQUENCY 设 为 2 时 ， 达 到 上 限 后 剔除 一 半 的 条 目 。 这 个 参数 的 
值 应 该 是 一 个 整数 ， 默 认为 3。 设 为 6 时， 达到 上 限 后 清空 整个 缓存 。 在 某 些 后 端 中 (尤其 是 
数据 库 后 端 ) ， 这 样 做 的 速度 更 快 ， 但 代价 是 有 更 多 的 缓存 缺失 。 














。 KEY_PREFIX: Django 服务 器 自动 在 所 有 缓存 键 中 加 入 (默认 放 在 开头 ) 的 一 个 字符 串 。 

。 VERSION: Django 服务 器 生成 的 缓存 键 的 默认 版 本 号 。 

。 KEY_FUNCTION: 表示 一 个 函数 的 点 分 路 径 字 符 串 。 对 应 的 函数 定义 如 何 由 前 缀 、 版 本 号 和 键 构成 最 终 
的 缓存 键 。 








下 述 示例 配置 一 个 文件 系统 后 端 ， 把 超时 时 间 设 为 60 秒 ， 把 最 大 容量 设 为 1000 条 : 


CACHES = { 
'default': { 
'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache', 
'LOCATION': '/var/tmp/django_cache', 
'TIMEOUT' : 60, 
'OPTIONS': {'MAX_ENTRIES': 1000} 


16.2 整 站 缓存 











配置 好 缓存 之 后 ， 使 用 缓存 最 简单 的 方式 是 缓存 整个 网 站 。 为 此 ， 要 把 'django.middleware.cache.UpdateCa- 
cheMiddleware' 和 'django.middleware.cache.FetchFromCacheMiddleware' 添加 到 MIDDLEWARE_CLASSES 设置 


中 ， 如 下 所 示 : 











MIDDLEWARE_CLASSES = [ 
'django.middleware.cache.UpdateCacheMiddleware', 
'django.middleware.common.CommonMiddleware', 
'django.middleware.cache.FetchFromCacheMiddleware', 


提醒 


注意 ， 我 没 写 错 ，UpdateCacheMiddleware 必须 放 在 列表 的 开头 ， 而 且 FetchFromCacheMiddle- 
ware 必须 放 在 列表 的 末尾 。 有 具体 原因 有 点 费解 ， 如 果 你 想 全 面 了 解 ， 请 阅读 17.5 节 。 





然后 ， 把 下 述 必须 的 设置 添加 到 Django 设置 文件 中 


。 CACHE_MIDDLEWARE_ALIAS: 存储 时 使 用 的 缓存 别名 。 
。 CACHE_MIDDLEWARE_SECONDS: 每 个 页 面 要 缓存 的 秒 数 。 


。 CACHE_MIDDLEWARE_KEY_PREFIX: 如 果 组 存在 使 用 同一 个 Django 的 多 个 网 站 中 共享 ， 把 这 个 设置 设 为 网 
站 的 名 称 ， 或 者 设 为 对 Django 实例 来 说 唯一 的 字符 串 ， 以 防 键 有 冲突 。 如 果 不 介 意 ， 设 为 空 字符 串 。 


























FetchFromCacheMiddLeware 缓存 请 求 和 首部 允许 缓存 的 ， 而 且 状 态 码 为 209 的 GET 和 HEAD 请 求 的 响应 。 针 对 
相同 URL 的 请 求 ， 如 果 查 询 参数 有 差 ， 响 应 视 为 不 同 的 ， 分 开 缓存 。 这 个 中 间 件 期 望 HEAD 请 求 的 响应 首部 
与 相应 的 GET 请 求 一 样 ， 这 样 遇 到 HEAD 请 求 就 能 返回 缓存 的 GET 响应 。 此 外 ，UpdateCacheMiddLeware 会 自动 
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为 各 个 HttpResponse 对 象 设 定 几 个 首部 : 


。 请 求 页 面 的 全 新 (未 缓存 ) 版 时 ， 把 Last-Modified 首部 设 为 当前 日 期 和 时 间 。 
。 把 Expires 首部 设 为 当前 日 期 和 时 间 减 去 CACHE_MIDDLEWARE_SECONDS 后 得 到 的 值 。 


。 设 定 Cache-Control 首部 ， 为 页 面 指定 最 长 有 效 期 。 同 样 ， 也 要 减 去 CACHE_MIDDLENARE_SECONDS 设 
置 。 



























































如 果 视 图 设 定 了 缓存 的 过 期 时 间 ( 即 cache-Control 首部 中 有 max-age 部 分 ) ， 页 面 的 缓存 将 持续 到 那个 时 
间 ， 而 不 考虑 CACHE_MIDDLEWARE_SECONDS。 使 用 django.views.decorators.cache 中 的 装饰 器 可 以 轻易 设 定 视 
图 的 过 期 时 间 (使 用 cache_control 装饰 器 ) ， 或 者 禁用 缓存 (使 用 never_cache 装饰 器 ) 。 这 些 装饰 器 的 详 
细 说 明 参 见 16.8 市 。 
















































































如 果 USE_I18N 设置 的 值 为 True， 生 成 的 缓存 键 包 含 当前 语言 的 名 称 。 这 样 无 需 人 工 干预 就 能 缓存 多 语言 网 


站 oo 














USE_L10N 设置 的 值 为 True 时 缓存 键 中 也 包含 当前 语言 的 名 称 。USE_Tz 设置 的 值 为 True 时 ， 缓 存 键 中 还 包含 
当前 时 区 。 








16.3 视图 层 缓存 














缓存 框架 更 细 粒 度 的 使 用 方式 是 缓存 单个 视图 的 输出 。django.views.decorators.cache 定义 的 cache_page 装 
饰 器 可 以 自动 缓存 视图 的 响应 ， 使 用 方法 很 简单 : 









































from django.views.decorators.cache import cache_page 


che_page(60 * 15) 
def my_view(request): 























cache_page 只 有 一 个 参数 ， 用 于 设 定 缓存 超时 的 秒 数 。 在 上 例 中 ，my_view() 视图 的 结果 缓存 15 分 钟 。 ( 注 
意 ， 为 了 便于 理解 ， 我 用 的 是 66 * 15， 即 15 个 60 秒 ， 等 于 900。) 
























































视图 层 的 缓存 与 整 站 缓存 一 样 ， 一 个 URL 对 应 一 个 键 。 如 果 多 个 URL 指向 同一 个 视图 ， 每 个 URL 单独 组 
存 。 仍 以 my_view 视图 为 例 ， 如 果 URL 配置 是 这 样 的 : 




















urlpatterns = [ 
url(r'^foo/([0-9]{1,2})/$', my_view), 
] 





那么 针对 /foo/1/ 和 /foo/23/ 的 请 求 分 开 缓 存 。 一 旦 请 求 了 特定 的 URL (如 /foo/23/) ， 后 续 对 那个 URL 
的 请 求 将 使 用 缓存 。 




















cache_page 还 接受 一 个 可 选 的 关键 字 人 参数 cache， 指 定 使 用 特定 的 缓存 (CACHES 设置 中 的 某 一 个 ) 存储 结 
果 。 








默认 使 用 default 缓存 ， 不 过 你 可 以 根据 需要 任意 指定 : 


Qcache_page(60 * 15, cache="special cache") 


def my_view(request): 











此 外 ， 在 视图 层 还 可 以 覆盖 缓存 前 级 。cache_page 的 可 选 关 键 字 参数 key_prefix 作用 与 中 间 件 的 CACHE_MID- 
DLEWARE_KEY_PREFIX 设置 一 样 。 下 面 举 个 例子 : 
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@cache_page(60 * 15, key_prefix="site1") 
def my_view(request): 


key_prefix 和 cache 参数 可 以 同时 指定 。key_prefix 参数 的 值 将 和 CACHES 设置 中 指定 的 KEY_PREFIX 拼接 在 一 
起 。 


16.3.1 在 URL 配置 中 指定 视图 层 缓存 





前 面 几 个 缓存 视图 的 例子 是 硬 编码 的 ， 因 为 cache_page 将 就 地 更 改 my_view 函数 。 这 么 做 把 视图 和 缓存 系统 
耦合 在 一 起 了 ， 并 不 妥当 。 原 因 有 几 方 面 。 例 如 ， 你 可 能 想 在 另 一 个 不 用 缓存 的 网 站 中 复 用 视图 函数 ， 或 者 
想 把 视图 提供 给 不 需要 缓存 的 人 使 用 。 
这 些 问 题 的 解决 方法 是 在 URL 配置 中 指定 视图 层 缓存 ， 而 不 在 视图 函数 上 指定 。 方 法 很 简单 ， 在 URL 配置 
中 使 用 cache_page 包装 视图 函数 。 


下 面 是 前 述 示例 中 的 URL 配置 : 





































































































urlpatterns = [ 
url(r'^foo/([0-9]{1,2})/$', my_view), 
] 


下 面 的 URL 配置 与 之 等 效 ， 不 过 my_view 包装 在 cache_page 中 : 





from django.views.decorators.cache import cache_page 
urlpatterns = [ 


url(r'^foo/([0-9]{1,2})/$', cache page(60 * 15)(my_view)), 
] 


16.4 模板 片段 缓存 








如 果 想 更 进一步 控制 ， 还 可 以 使 用 cache 模板 标签 缓存 模板 片段 。 为 了 能 在 模板 中 使 用 这 个 标签 ， 在 靠近 模 
板 顶 部 的 位 置 写 上 {% load cache %}。{% cache %} 模板 标签 缓存 块 中 的 内 容 一 段 时 间 。 





























至 少 要 为 {% cache %]} 标签 提供 两 个 参数 ， 一 个 设 定 缓存 超时 的 秒 数 ， 另 一 个 为 缓存 的 片段 命名 。 这 个 名 称 
原封 不 动 ， 不 视 作 变 量 。 


例如 : 











{% Load cache %} 

{% cache 500 sidebar %} 
. Sidebar .. 

{% endcache %} 





有 时 可 能 想 根 据 动 态 片段 中 的 内 容 缓存 多 份 。 例 如 ， 分 别 为 网 站 中 的 各 个 用 户 缓 存 上 例 中 的 侧 边栏 。 为 此 ， 
再 给 {% cache % 模板 标签 传人 一 个 参数 ， 用 于 唯一 标识 缓存 片段 : 

















{% Load cache %} 

{% cache 500 sidebar request.user.username %} 
. Sidebar for Logged in user .. 

{% endcache %} 








为 了 标识 片段 ， 完 全 可 以 传人 多 个 参数 。 直 接 把 额外 的 参数 传 给 {% cache 季 标签 即 可 。 如 果 把 USE_I18N 设 
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为 True， 整 站 缓存 中 间 件 将 考虑 当前 语言 。 




















在 cache 模板 标签 中 可 以 使 用 一 个 翻译 专用 的 变量 达到 同样 的 效果 : 








{% Load 118n %} 
{% Load cache %} 


{% get_current_Language as LANGUAGE CODE %} 
{% cache 600 welcome LANGUAGE_CODE %} 


{% trans "Welcome to example.com" %} 
{% endcache %} 


缓存 超时 时 间 可 以 通过 模板 变量 指定 ， 只 要 那个 变量 最 终 得 到 的 值 是 一 个 整数 就 行 。 

















例如 ， 如 果 my_timeout 模板 变量 的 值 是 666， 那 么 下 面 两 行 代码 是 等 效 的 : 





{% cache 600 sidebar %} ... {% endcache %} 
{% cache my_timeout sidebar %} ... {% endcache %} 


这 样 可 以 避免 模板 中 有 重复 。 你 可 以 在 一 处 定义 一 个 变量 ， 指 定 超时 时 间 ， 然 后 在 多 个 地 方 复 用 。cache 标 
签 默认 尝试 使 用 名 为 template_fragments 的 缓存 。 如 果 这 个 缓存 不 存在 ， 使 用 default 缓存 。 可 以 使 用 using 
关键 字 参 数 (必须 是 最 后 一 个 参数 ) 选择 缓存 后 端 。 















































{% cache 300 local-thing ... using="localcache" %} 





指定 未 配置 的 缓存 会 出 错 。 


如 果 想 获取 缓存 片段 所 用 的 绥 存 键 ， 使 用 make_tempLate_fragment_key(fragment_name，vary_on=None) 也 
数 。fragment_name 的 值 等 于 cache 模板 标签 的 第 二 个 参数 ，vary_on 是 一 个 列表 ， 包 含 传 给 cache 标签 的 所 
可 额外 参数 。 可 以 使 用 这 个 函数 撤销 或 覆盖 一 个 缓存 条 目 ， 例 如 : 






































>>> from django.core.cache import cache 

>>> from django.core.cache.utils import make_tempLate_fragment_key 
# {% cache 500 sidebar username %} 的 缓存 键 

>>> key = make_template fragment key('sidebar', [username]) 

>>> cache.delete(key) # 删除 缓存 的 模板 片段 


16.5 低层 缓存 API 








时 ， 缓 存 泻 染 的 整个 页 面 没有 实际 意义 ， 而 且 有 点 过 。 你 的 网 站 中 可 能 有 这 人 么 一 个 视图 ， 它 的 结果 由 多 个 
耗资 源 的 查询 得 到 ， 而 且 会 随 着 时 间 而 变 。 此 时 就 不 适合 使 用 整 站 或 视图 层 缓存 策略 缓存 整个 页 面 ， 因 为 不 
能 缓存 整个 结果 〈 部 分 数据 经 常 变动 ) ， 但 是 仍 想 缓存 很 少 变化 的 结果 。 


为 此 ，Django 提供 了 简单 的 低层 缓存 API。 使 用 这 个 API 可 以 按照 任何 你 想 要 的 粒度 把 对 象 存 人 缓存 。 任 何 
能 安全 序列 化 的 Python 对 象 都 可 以 缓存 ， 例 如 字符 串 、 字 典 、 模 型 对 象 列表 ， 等 等 。 〈 多 数 常见 的 Python 
对 象 都 能 序列 化 ， 详 情 参见 Python 文档 。 ) 







































































16.5.1 访问 缓存 




















CACHES 设置 中 配置 的 缓存 通过 类 似 字 典 的 对 和 象 访问 一 一 django.core.cache.caches。 在 同一 个 线程 中 重复 请 求 
相同 的 别名 得 到 的 是 相同 的 对 象 。 











>>> from django.core.cache import caches 
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>>> cachel = caches[ 'myaLias '] 
>>> cache2 = caches['myalias'] 
>>> cachel is cache2 

True 








指定 的 键 不 存在 时 ， 抛 出 InvaLidCacheBackendError。 为 了 保证 线程 安全 ， 每 个 线程 使 用 不 同 的 缓存 后 端 实 
例 。 











默认 的 缓存 可 以 使 用 简洁 的 django.core.cache.cache 访问 : 
>>> from django.core.cache import cache 


这 个 对 象 等 同 于 caches[ 'default']。 





16.5.2 基本 用 法 


基本 的 接口 是 set(key, value, timeout) 和 get(key): 


>>> cache.set('my_key', 'hello, world!', 30) 
>>> cache.get('my_key') 
'hello, world!' 














timeout 参数 是 可 选 的 ， 默 认 等 于 CACHES 设置 中 相应 后 端的 timeout 选项 (参见 前 文 ) 。 这 个 参数 的 作用 是 
设 定 值 在 缓存 中 存储 的 秒 数 。 设 为 None 时 ， 永 久 缓存 ， 设 为 6 时 ， 不 缓存 。 如 果 缓 存 中 没有 对 象 ， 


cache.get() 返回 None。 


























# 等 30 秒 ,， 让 my_key 过 期 .… 


>>> cache.get('my_key') 
None 








不 建议 在 缓存 中 存储 字面 值 None， 因 为 返回 None 时 无 法 区 分 是 存储 的 None 值 ， 还 是 由 于 缓存 缺失 而 导致 的 
返回 值 。 可 以 在 cache.get() 中 指定 一 个 默认 值 ， 即 缓存 中 没有 对 象 时 返回 的 值 。 























>>> cache.get('my_key', 'has expired') 
'has expired ' 





如 果 只 想 在 键 不 存在 时 添加 键 ， 使 用 add() 方法 。 它 的 参数 与 set() 一 样 ， 但 是 如 果 指 定 的 键 已 经 存在 ， 不 
会 更 新 缓存。 





>>> cache.set('add key', 'Initial value') 
>>> cache.add('add_key', 'New value') 

>>> cache.get('add_key') 

'Initial value' 








为 了 确认 add() 是 否 把 值 存 储 到 缓存 中 了 ， 可 以 检查 它 的 返回 值 。 如 果 存 储 了 值 ，add() 返回 True， 否 则 返 
回 False。 此 外 ， 还 有 个 get_many() 接口 ， 它 只 访问 缓存 一 次 。get_many() 返回 一 个 字典 ， 包 含 你 查询 的 各 
个 键 中 确实 存在 而 且 没 有 过 期 的 那 部 分 。 
























































>>> cache.set('a', 1) 

>>> cache.set('b', 2) 

>>> cache.set('c', 3) 

>>> cache.get many(['a', 'b', 'c']) 
人 
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若 想 高 效 设 定 多 个 值 ， 使 用 set_many()， 它 的 参数 是 键 值 对 构成 的 字典 : 














>>> cache.set many({'a': 1，'b': 2, 'c': 3}) 
>>> cache.get many(['a'’, 'b', 'c']) 
pe | A 4 


与 cache.set() 一样 ，set_many() 有 个 可 选 的 timeout 参数 。 





键 使 用 detete() 删除 。 从 缓存 中 删除 特定 对 象 的 简易 方式 如 下 : 





>>> cache.delete('a') 


























若 想 一 次 删除 多 个 键 ， 使 用 delete_many()， 它 的 参数 是 要 删除 的 键 列表 : 


>>> cache.delete many(['a', 'b', 'c']) 














最 后 ， 若 想 删 除 缓存 中 的 全 部 键 ， 使 用 cache.clear()。 注 意 ，clear() 将 删除 缓存 中 的 一 切 ， 而 不 只 是 由 应 
用 程序 设 定 的 键 。 




















>>> cache.clear() 














现存 的 键 可 以 分 别 使 用 incr() 和 decr() 递增 和 递减 。 默 认 ， 递 增 或 递减 的 量 是 1。 如 果 想 使 用 其 他 量 ， 为 
incr() 和 decr() 提供 第 二 个 参数 。 




















如 果 尝 试 递 增 或 递减 不 存在 的 缓存 键 ， 抛 出 ValueError。 


>>> cache.set('num', 1) 
>>> cache.incr('num') 

巡 

>>> cache.incr('num', 10) 
12 

>>> cache.decr('num') 

1 

>>> cache.decr('num', 5) 
6 


可 以 使 用 close() 《前提 是 缓存 后 端 实现 了 ) 关闭 与 缓存 的 连接 。 





>>> cache.close() 


注意 ， 对 没有 实现 close() 方法 的 缓存 后 端 来 说 ， 调 用 它 没 有 实际 作用 。 


16.5.3 缓存 键 的 前 组 


如 果 在 多 个 服务 器 之 间 共 享 缓存 实例 ， 或 者 在 生产 环境 和 开发 环境 之 间 共 享 ， 一 个 服务 器 缓存 的 数据 可 能 会 
被 另 一 个 服务 器 使 用 。 因 而 ， 如 果 不 同 服务 器 缓存 的 数据 格式 没有 区 别 ， 可 能 导致 特别 难以 诊断 的 问题 。 


为 了 避免 这 种 问题 ，Django 支持 为 一 个 服务 器 的 所 有 缓存 键 添 加 前 级 。 保 存 或 读 取 缓 存 键 时 ，Django 会 自动 
在 前 面 加 上 KEY_PREFIX 设置 设 定 的 值 。 为 不 同 的 Django 实例 设 定 不 同 的 KEY_PREFIX， 能 确保 缓存 值 之 间 没 
有 冲突 。 



























































16.5.4 缓存 的 版 本 


修改 使 用 缓存 的 线 上 代码 后 ， 可 能 需要 清除 全 部 现 有 的 缓存 值 。 这 个 操作 最 简单 的 做 法 是 把 整个 缓存 删 掉 ， 
但 是 仍然 有 效 、 仍 然 有 用 的 缓存 值 也 丢失 了 。 为 了 甄别 要 删除 的 缓存 值 ，Django 提供 了 更 好 的 方法 。 
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Django 的 缓存 框架 有 个 系统 全 局 版 本 标识 符 ， 由 缓存 设置 中 的 VERSION 选项 指定 。Django 结合 前 级 、 用 户 提 

















供 的 缓存 键 和 这 个 设置 的 值 获取 最 终 的 缓存 键 。 









































定 想 设 定 或 读 取 的 缓存 键 版 本 。 例 如 : 





# 设 定 缓存 键 的 第 2 版 
>>> cache.set('my_key', 'hello worLd!' ，version=2) 
# 获取 默认 版 本 (假定 版 本 为 1) 

>>> cache.get('my_key') 

None 

# 获取 这 个 键 的 第 2 版 

>>> cache.get('my_key', version=2) 

'hello worLd! 











而 其 他 键 则 不 受 影响 。 接 着 上 例 : 


# 递增 my_key 的 版 本 号 

>>> cache.incr_version('my_key') 
# 默认 版 本 依然 不 存在 

>>> cache.get('my_key') 

None 

# 第 2 版 也 不 存在 了 

>>> cache.get('my_key', version=2) 
None 

# 但 是 第 3 版 存在 

>>> cache.get('my_key', version=3) 
'hello worLd! 


16.5.5 缓存 键 的 组 合 方式 


默认 情况 下 ， 对 键 的 请 求 自动 包含 默认 的 缓存 版 本 号 。 然 而 ， 主 要 的 缓存 函数 都 有 个 version 参数 ， 用 于 指 


键 的 版 本 号 可 以 分 别 使 用 incr_version() 和 decr_version() 递增 和 递减 。 这 样 可 以 把 指定 的 键 升 到 新 版 本 ， 





前 文 说 过 ， 用 户 提供 的 缓存 键 并 不 是 最 终 使 用 的 值 ， 还 要 加 上 前 缀 和 版 本 号 。 默 认 情 况 下 ， 这 三 部 分 使 用 














号 连接 在 一 起 ， 组 成 最 终 的 字符 串 ; 





def make_ key(key, key_prefix, version): 


return ':'.join([key_prefix, str(version), key]) 








如 果 想 以 其 他 方式 组 合 这 三 部 分 ， 或 者 相对 最 终 得 到 的 键 做 其 他 处 理 (例如 计算 键 的 哈 希 摘要 ) ， 可 以 














| 








定 











义 生成 键 的 函数 。CACHES 设置 中 的 KEY_FUNCTION 选项 用 于 指定 一 个 函数 的 点 分 路 径 ， 函 数 的 原型 如 上 所 示 。 





























如 果 提 供 这 个 选项 ， 将 使 用 指定 的 函数 代 将 默认 的 键 组 合 函 数 。 














16.5.6 缓存 键 相关 的 警告 









































生产 环境 最 常 使 用 的 缓存 后 端 Memcached 不 允许 缓存 键 的 长 度 超过 250 个 字符 ， 也 不 允许 包含 空白 或 控制 字 


符 。 如 若 不 然 ， 会 导致 异常 抛 出 。 为 了 促进 不 同 后 端 之 间 的 兼容 性 ， 尽 量 减 少 意外 情况 ， 内 置 的 其 他 几 个 组 




















存 后 端 遇 到 能 导致 Memcached 出 错 的 键 时 会 发 出 警告 (django.core.cache.backends.base.CacheKeyNarn 
ing) 。 








如 果 你 在 生产 环境 中 使 用 的 后 端 〈 自 定义 的 后 端 ， 或 者 是 Memcached 之 外 的 内 置 后 端 ) 能 接受 更 大 范围 



































CacheKeyWarning.: 


键 ， 而 且 不 想 看 到 这 样 的 警告 ， 可 以 在 INSTALLED_Apps 中 的 某 个 应 用 的 management 模块 里 使 用 下 述 代码 静默 


的 
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import warnings 
from django.core.cache import CacheKeyWarning 


warnings.simplefilter("ignore", CacheKeyWarning) 


如 果 想 自 定义 内 置 后 端 验 证 键 的 逻辑 ， 可 以 定义 后 端的 子 类 ， 只 覆盖 validate_key 方法 ， 然 后 按照 16.1.6 节 
的 说 明 做 。 


例如 ， 对 本 地 内 存 后 端 来 说 ， 在 一 个 模块 中 编写 下 述 代 码 : 


























from django.core.cache.backends.Locmem import LocMemCache 


class CustomLocMemCache(LocMemCache): 
def validate key(self, key): 
# 自 定义 验证 逻辑 ， 根 据 需 要 抛 出 异常 或 发 出 警告 
本 











然后 ， 在 CACHES 设置 中 把 BACKEND 设 为 这 个 类 的 点 分 Python 路 径 。 











16.6 下 游 缓 存 


目前 ， 本 章 集 中 讨论 的 是 如 何 缓存 自己 的 数据 。 但 是 ， 与 Web 开发 有 关 的 还 有 一 种 缓存 : 由 下 游 缓 存 所 做 的 
缓存 。 这 是 系统 做 的 缓存 ， 发 生 在 请 求 到 达 网 站 之 前 。 下 面 是 几 个 下 游 缓存 的 例子 : 


























。 ISP 可 能 缓存 某 些 页 面 ， 当 你 访问 页 面 时 (如 http://example.com/) ，ISP 直接 返回 缓存 的 页 面 ， 根 
本 不 去 访问 http://example.com/。http://example.com/ 的 维护 人 员 对 这 种 缓存 一 无 所 知 ，ISP 位 于 网 
站 和 Web 浏览 器 之 间 ， 悄 无 声息 地 处 理 所 有 缓存 。 

。 Django 网 站 可 能 在 代理 缓存 (proxy cache) 后 面 ,例如 Squid Web Proxy Cache， 为 了 提升 性 能 ， 代 理 
缓存 会 缓存 页 面 。 此 时 ， 请 求 首先 由 代理 处 理 ， 只 在 需要 时 才 发 给 你 的 应 用 程序 。 

。 Web 浏览 器 也 会 缓存 页 面 。 如 果 网 页 发 送 适 当 的 首部 ， 后 续 对 那个 页 面 的 请 求 会 使 用 浏览 器 本 地 缓存 
的 副本 ， 甚 至 不 会 询问 网 页 有 没有 变化 。 






















































































下 游 缓 存 能 在 一 定 程度 上 提高 效率 ， 但 是 也 有 和 危害: 很 多 网 页 的 内 容 根据 通过 身份 验证 与 否 ， 以 及 一 堆 其 他 
变量 而 变 ， 假 若 缓 存 系 统 育 目地 只 基于 URL 保存 页 面 ， 可 能 导致 后 续 访 问 者 看 到 不 正确 或 敏感 的 数据 。 









































以 Web 电子 邮件 系统 为 例 。 显 然 ， 收 件 箱 的 内 容 取 决 于 所 登录 的 用 户 。 如 果 ISP 盲目 地 缓存 ， 后 面 的 访问 者 
就 能 看 到 之 前 登录 用 户 的 收 件 箱 。 这 可 不 好 。 

幸好 ，HTTP 为 这 个 问题 提供 了 解决 方案 。 有 几 个 HTTP 首部 用 于 指示 下 游 缓 存 ， 根 据 指定 变量 区 分 缓存 的 
内 容 ， 以 及 不 缓存 特定 的 页 面 。 接 下 来 的 几 节 介绍 这 些 首 部 。 
























































16.7 使 用 vary 首部 


























Vary 首部 定义 缓存 机 制 构建 缓存 键 时 要 考虑 的 请 求 首 部 。 例 如 ， 如 果 一 个 网 页 的 内 容 取决 于 用 户 的 语言 偏好 
设置 ， 那 个 页 面 就 在 语言 上 有 区 别 。Django 的 缓存 系统 默认 使 用 所 请 求 页 面 的 完全 限定 URL (如 
http://www.example.com/stories/2005/?order_by=author ) 创建 缓存 键 。 












































这 意味 着 ， 对 那个 URL 的 所 有 请 求 都 使 用 同一 个 缓存 版 本 ， 而 不 管用 户 代理 的 区 别 ， 例 如 cookie 或 语言 偏 
好 设置 。 然 而 ， 如 果 页 面 根据 请 求 首部 (如 cookie、 语 言 或 用 户 代理 ) 的 不 同 而 生成 不 同 的 内 容 ， 就 要 通过 
Vary 首部 告诉 缓存 机 制 页 面 的 内 容 由 这 些 首部 而 定 。 
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为 此 ， 在 Django 中 使 用 便利 的 django.views.decorators.vary.vary_on_headers() 视图 装饰 器 ， 如 下 所 示 : 





from django.views.decorators.vary import vary_on_headers 


@vary_on_headers('User-Agent') 
def my_view(request): 





此 时 ， 缓 存 系统 (例如 Django 的 缓存 中 间 件 ) 会 针对 不 同 的 用 户 代 理 创 建 单独 的 缓存 。 与 自己 动手 设 定 
Vary 首部 (例如 response['Vary'] = 'user-agent') 相 比 ， 使 用 vary_on_headers 装饰 器 的 好 处 是 ， 它 把 内 
容 添 加 到 Vary 首部 中 (可 能 已 有 内 容 ) ， 而 不 是 全 新 设 定 ， 导 致 现 有 内 容 被 覆盖 。 可 以 把 多 个 首部 传 给 


vary_on_headers() : 
































Gvary_on_headers('User-Agent' ， "Cookie ') 
def my_view(request): 
和 














这 样 设置 的 作用 是 ， 告 诉 下 游 缓 存 ， 每 个 用 户 代 理 和 cookie 的 组 合 都 有 自己 单独 的 缓存 值 。 例 如 ， 用 户 代理 
为 “Mozilla”、cookie 值 为 “foo=bar”* 的 请 求 ， 与 用 户 代 理 为 “Mozilla”， 而 cookie 值 为 “foo=ham” 的 请 求 是 不 同 
的 。 因 为 经 常会 区 别 cookie， 所 以 Django 提供 了 django.views.decorators.vary.vary_on_cookie() 装饰 器 。 

下 面 两 个 视图 是 等 效 的 : 





















































Gvary_on_cookle 


def my_view(request): 


a 
@vary_on_headers('Cookie') 
def my_view(request): 

# ... 


传 给 vary_on_headers 的 首部 不 区 分 大 小 写 ， 因 此 'User-Agent' 与 'user-agent' 指 的 是 同一 个 首部 。 此 外 ， 
还 可 以 直接 使 用 辅助 函数 django.utils.cache.patch_vary_headers()。 这 个 函数 用 于 设 定 或 把 内 容 添 加 到 
Vary 首部 中 。 例 如 : 























from django.utils.cache import patch_vary_headers 


def my_view(request): 
a 
response = render_to_response('template name', context) 
patch_vary_headers(response, ['Cookie']) 
return response 





patch_vary_headers 函数 的 第 一 个 参数 是 一 个 HttpResponse 实例 ， 第 二 个 参数 是 由 首部 名 称 (不 区 分 大 小 
写 ) 构成 的 列表 或 元 组 。Vvary 首部 的 详细 信息 参见 官方 规范 。 


























16.8 使 用 其 他 首部 控制 缓存 























与 缓存 有 关 的 其 他 问题 还 有 数据 隐私 和 数据 存储 在 层 释 缓 存 的 什么 位 置 。 通 常 ， 用 户 面 对 的 有 两 种 缓存 : 浏 
览 器 的 缓存 (私有 缓存 ) 和 提供 商 的 缓存 (公开 缓存 ) 。 


公开 缓存 供 多 人 使 用 ， 由 别人 控制 。 对 敏感 数据 来 说 ， 这 会 导致 一 些 问题 ， 因 为 你 不 想 让 自己 的 银行 账号 存 
储 在 公开 缓存 中 。 所 以 ，Web 应 用 要 通过 一 种 方式 告诉 缓存 哪些 数据 是 私有 的 ， 哪 些 是 公开 的 。 


















































250 - 第 16 章 Django 的 缓存 框架 


为 此 ， 含 有 私有 数据 的 页 面 要 告知 缓存 。 在 Django 中 ， 使 用 的 是 cache_control 视图 装饰 器 。 例 如 : 


from django.views.decorators.cache import cache_control 


@cache_control(private=True) 
def my_view(request): 











这 个 装饰 器 在 背后 会 发 送 合 适 的 HITP 首部 。 注 意 ， 在 这 里 设 定 的 private 和 public 是 互 斥 的 。 如 果 应 该 设 
为 私有 的 ， 它 会 把 公开 指令 删除 (反之 亦 然 ) 。 


在 同时 具有 私有 文章 和 公开 文章 的 博客 中 就 可 以 使 用 这 两 个 指令 。 公 开 的 文章 可 以 在 共享 的 缓存 中 缓存 。 下 
述 示例 使 用 django.utils.cache.patch_cache_control() 困 数 (cache_control 装饰 器 在 内 部 调用 它 ) 手动 修 
改 缓存 控制 首部 : 





























from django.views.decorators.cache import patch_cache_control 
from django.views.decorators.vary import vary_on_cookie 


@vary_on_cookie 
def list blog entries view(request): 
if request.user.is_anonymous(): 
response = render_only_public entries() 
patch_cache_control(response, public=True) 
else: 
response = render_private_and_public_entries(request.user) 
patch_cache_control(response, private=True) 


return response 
控制 缓存 参数 还 有 其 他 方式 。 例 如 ，HTTP 允许 应 用 程序 这 么 做 : 


。 定义 页 面 缓存 的 最 长 时 间 。 


。 指定 是 否 检查 新 版 ， 仅 在 没有 变化 时 使 用 缓存 的 内 容 。 〈 有 些 缓存 即使 发 现 页 面 内 容 有 变 仍然 发 送 组 
存 的 内 容 ， 只 是 因为 缓存 的 副本 尚未 过 期 。) 











在 Django 中 ， 这 些 缓存 参数 使 用 cache_control 视图 装饰 器 指定 。 在 下 面 的 示例 中 ，cache_controt 告诉 组 
存 ， 每 次 访问 都 重新 验证 缓存 ， 而 且 至 少 存储 缓存 的 版 本 3600 秒 : 




















from django.views.decorators.cache import cache_control 


@cache_control(must_revalidate=True, max_age=3600) 
def my_view(request): 
Ds 





有 效 的 Cache-Control 首部 指令 都 能 传 给 cache_control() 装饰 器 。 完 整 的 指令 列表 如 下 : 


。 public=True 

。 private=True 

。 no_cache=True 

。 no_transform=True 


。 must_ revalidate=True 
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。 proxy_revalidate=True 
。 max_age=num_seconds 


。 S_maxage=num_seconds 





Cache-Control 指令 的 完整 说 明 参 见 规范 。 (注意 ， 缓 存 中 间 件 已 经 把 首部 的 max-age 指令 设 为 CACHE_MID- 
DLEWARE_SECONDS 设置 的 值 。cache_control 装饰 器 中 指定 的 max_age 参数 优先 采用 ， 而 且 能 正确 合并 到 
Cache-Control 首部 中 。) 












































如 果 想 设 定 彻底 禁止 缓存 的 首部 ， 使 用 django.views.decorators.cache.never_cache 视图 装饰 器 。 这 个 装饰 
器 添加 的 首部 确保 响应 不 会 被 浏览 器 或 其 他 设备 缓存 。 例 如 : 























from django.views.decorators.cache import never_cache 
QnNever 


def myview(request): 
WE 


16.9 接 下 来 





下 一 章 探讨 Django 的 中 间 件 。 
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第 17 章 Django 中 间 件 


中 间 件 是 插 在 Django 的 请 求 和 响应 过 程 之 中 的 框架 。 这 是 一 种 轻 量 级 的 低层 插件 系统 ， 用 于 全 局 调整 Djan- 
go 的 输入 或 输出 。 


一 个 中 间 件 组 件 专 注 于 做 一 件 特定 的 事 。 例 如 ，Django 使 用 AuthenticationMiddleware 这 个 中 间 件 组 件 处 理 
带 会 话 的 请 求 。 


本 章 说 明 中 间 件 的 工作 方式 、 如 何 激活 中 间 件 ， 以 及 如 何 自 己 动手 编写 中 间 件 。Dijango 自 带 了 一 些 中 间 件 ， 
拿 来 即 用 。 人 参见 174 市 。 
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17.1 激活 中 间 件 








震 想 激活 一 个 中 间 件 组 件 ， 把 它 添加 到 Django 设置 文件 中 的 MIDDLEWARE_CLASSES 列表 里 。 























MIDDLEWARE_CLASSES 设置 中 的 各 个 中 间 件 组 件 使 用 字符 串 表示 ， 这 个 字符 串 是 中 间 件 类 名 的 完整 Python 路 
径 。 例 如 ， 下 面 是 使 用 django-admin startproject 命令 创建 项 目 后 得 到 的 默认 值 : 












































MIDDLEWARE_CLASSES = [ 
'django.contrib.sessions.middleware.SessionMiddleware', 
'django.middleware.common.CommonMiddleware', 
'django.middleware.csrf.CsrfViewMiddleware', 
'django.contrib.auth.middleware.AuthenticationMiddleware', 
'django.contrib.messages.middleware.MessageMiddleware', 
'django.middleware.clickjacking.XFrameOptionsMiddleware', 


] 








没有 任何 中 间 件 是 必须 的 ， 如 果 愿 意 ，MIDDLEWARE_CLASSES 列表 可 以 为 空 ， 但 是 强烈 建议 至 少 要 使 用 Common- 


Middleware, 








MIDDLEWARE_CLASSES 要 按照 一 定 顺 序 罗列 中 间 件 ， 因 为 中 间 件 之 间 可 能 彼此 依赖 。 例 如 ，AuthenticationMid- 
dleware 在 会 话 中 存储 通过 身份 验证 的 用 户 ， 因 此 必须 列 在 SessionMiddleware 后 面 。 常 见 Django 中 间 件 类 
的 顺序 参见 17.5 市 。 
































17.2 钩子 和 应 用 中 间 件 的 顺序 








处 理 请 求 时 ， 在 调用 视图 之 前 ，Django 按照 MIDDLEWARE_CLASSES 列 出 的 顺序 从 上 到 下 应 用 各 个 中 间 件 。 这 期 
间 有 两 个 钩子 可 用 : 





。 process_request() 


。 process_view() 





处 理 响 应 时 ， 在 调用 视图 之 后 ，Django 按照 相反 的 顺序 从 下 到 上 应 用 各 个 中 间 件 。 这 期 间 有 三 个 钩子 可 用 : 











。 process_exception() 


。 process_template_response() 
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。 process_response() 





你 可 以 把 这 种 结构 想象 成 洋 殴 ， 外 层 中 间 件 类 包 囊 着 内 层 视图 。 下 面 分 述 各 个 钩子 。 


17.3 自己 动手 编写 中 间 件 
自己 编写 中 间 件 不 难 。 一 个 中 间 件 组 件 就 是 一 个 Python 类 ， 其 中 定义 一 个 或 多 个 下 述 方法 。 


17.3.1 process_request 
方法 签名 : process_request(request) 


。 request 是 一 个 HttpRequest 对 象 。 
。 处 理 请 求 时 ，Django 在 决定 执行 哪个 视图 之 前 调用 process_request()。 


这 个 方法 应 该 返回 None 或 一 个 HttpResponse 对 象 。 如 果 返 回 None，Django 继续 处 理 请 求 ， 调 用 其 他 中 间 件 
中 的 process_request() 方法 ， 然 后 调用 process_view() 方法 ， 最 后 执行 恰当 的 视图 。 











如 果 返 回 一 个 HttpResponse 对 象 ，Django 不 再 调用 其 他 处 理 请 求 、 视 图 或 异常 的 中 间 件 ， 也 不 执行 视图 ， 而 
是 应 用 响应 中 间 件 ， 返 回 结果 。 








17.3.2 process_view 
方法 签名 : process_view(request, view func, view args, view kwargs) 


。 request 是 一 个 HttpRequest 对 象 。 

。 view_func 是 Django 将 使 用 的 Python 函数 。 (是 函数 对 象 ， 而 非 函 数 名 称 的 字符 串 形式 。) 
。 view_args 是 要 传 给 视图 的 位 置 参数 列表 。 
。 view_kwargs 是 要 传 给 视图 的 关键 字 参 数字 典 。 

。 view_args 和 view_kwargs 中 都 不 包含 视图 的 第 一 个 参数 (request) 。 












































process_view() 方法 在 Django 调用 视图 之 前 的 最 后 一 刻 调 用 ， 应 该 返回 None 或 一 个 HttpResponse 对 象 。 如 
果 返 回 None，Django 将 继续 处 理 请 求 ， 调 用 其 他 中 间 件 中 的 process_view() 方法 ， 然 后 执行 恰当 的 视图 。 








如 果 返 回 一 个 HttpResponse 对 象 ，Django 不 会 再 调用 其 他 视图 或 异常 中 间 件 ， 也 不 执行 视图 ， 而 是 应 用 响应 
中 间 件 ， 返 回 结果 。 


在 中 间 件 的 process_request 或 process_view 方法 中 访问 request.P0ST 的 话 ， 在 中 间 件 之 后 运 
行 的 视图 无 法 修改 请 求 的 上 传 处 理 程序 ， 因 此 通常 不 应 该 这 么 做 。 





CsrfViewMiddleware 类 算是 一 个 例外 ， 它 提供 的 csrf_exempt() 和 csrf_protect() 装饰 器 用 于 控制 视图 在 何 
时 验证 CSRF。 


17.3.3 process_tempLate_response 


方法 签名 : process_template_response(request, response) 
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。 request 是 一 个 HttpRequest 对 象 。 
。 response 是 一 个 TempLateResponse 对 象 (或 其 他 等 效 的 对 象 ) ， 由 Django 视图 或 中 间 件 返回 。 
































process_template_response() 在 视图 执行 完毕 后 立即 调用 。 如 果 响 应 实例 有 render() 方法 ， 表 明 它 是 Tem- 
plateResponse 或 等 效 的 对 象 。 


process_template_response() 方法 必须 返回 一 个 实现 render 方法 的 响应 对 象 。 为 此 ， 可 以 修改 传人 的 re- 
sponse 的 response.tempLate_name 和 response.context_data， 也 可 以 创建 并 返回 全 新 的 TempLateResponse 或 
等 效 的 对 象 。 


无 需 自己 动手 浑 染 响应 ， 响 应 在 所 有 模板 响应 中 间 件 执行 完毕 后 自动 泻 染 。 


















































处 理 响应 时 ， 中 间 件 反 向 运行 ， 在 这 个 过 程 中 会 调用 process_tempLate_response() 。 





17.3.4 process_response 
方法 签名 : process_response(request, response) 


。 request 是 一 个 HttpRequest 对 象 。 


。 response 是 Django 视图 或 中 间 件 返回 的 HttpResponse 或 StreamingHttpResponse 对 象 。 














所 有 啊 应 在 返回 给 浏览 器 之 前 都 会 调用 process_response() 方法 。 这 个 方法 必须 返回 一 个 HttpResponse 或 
StreamingHttpResponse 对 象 。 为 此 ， 可 以 修改 传人 的 response， 或 者 创建 并 返回 全 新 的 HttpResponse 或 
StreamingHttpResponse 对 象 。 





























与 process_request() 和 process_view() 方法 不 同 ，process_response() 方法 始终 调用 ， 即 便 跳 过 了 所 在 中 间 
件 类 的 process_request() 和 process_view() 方法 也 是 如 此 (因为 前 面 的 中 间 件 返回 的 是 HttpResponse 对 
象 ) 。 因 此 ，process_response() 方法 不 能 依赖 process_request() 所 做 的 设置 。 
































最 后 ， 记 住 ， 人 处 理 响 应 时 ， 中 间 件 反 向 运行 ， 从 下 到 上 。 这 意味 着 ，MIDDLEWARE_CLASSES 中 的 最 后 一 个 中 间 
件 类 先 执行 。 








处 理 流 式 响 应 








与 HttpResponse 不 同 的 是 ，StreamingHttpResponse 没有 content 属性 。 因 而 ， 中 间 件 不 能 假定 所 有 响应 都 有 
content 属性 。 如 果 需 要 访问 内 容 ， 必 须 测 试 是 不 是 流 式 响应 ， 然 后 据 此 调整 行为 : 


ui 























if response.streaming: 

response.streaming_content = wrap_streaming_content(response.streaming_content) 
else: 

response.content = alter_content(response.content) 








streaming_content 应 该 视 作 非常 大 的 对 象 ， 内 存 中 放 不 下 。 响 应 中 间 件 可 以 使 用 一 个 新 的 生成 器 包装 它 ， 一 
定 不 能 直接 使 用 。streaming_content 经 常 像 下 面 这 样 包装 : 














def wrap_streaming_content(content): 
for chunk in content: 
yield alter_content(chunk) 


17.3.5 process_exception 


方法 签名 : process_exception(request, exception) 
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。 request 是 一 个 HttpRequest 对 象 。 














。 exception 是 一 个 Exception 对 象 ， 由 视图 函数 抛 出 。 








Django 在 视图 抛 出 异常 时 调用 process_exception() 方法 。 这 个 方法 应 该 返回 None 或 一 个 HttpResponse 对 
象 。 如 果 返 回 HttpResponse 对 象 ， 会 应 用 模板 啊 应 和 响应 中 间 件 ， 然 后 把 得 到 的 响应 返回 给 浏览 器 。 否 则 ， 
使 用 默认 的 方式 处 理 异常 。 





























再 次 强调 ， 处 理 响应 时 ， 中 间 件 反 向 运行 ， 其 中 包含 process_exception。 如 果 某 个 异常 中 间 件 返回 响应 ， 那 
个 中 间 件 上 面 的 中 间 件 类 不 再 调用 。 


























17.3.6 _init_ _ 








多 数 中 间 件 类 不 需要 定义 初始 化 方法 ， 因 为 中 间 件 类 基本 上 只 需 实现 各 个 process_* 方法 。 但 是 ， 如 果 需 要 
某 种 全 局 状态 ， 可 以 实现 _init_。 不 过 ， 要 留意 儿 个 问题 : 








1. Django 初始 化 中 间 件 时 不 传人 任何 参数 ， 因 此 你 定义 的 _init__ 方法 不 能 有 参数 。 
2. process_* 方 法 每 次 请 求 调用 一 次 ， 而 _init “只 在 Web 服务 器 响应 第 一 个 请 求 时 调用 一 次 。 









































把 中 间 件 标记 为 不 使 用 





时 需要 在 运行 时 判断 是 否 应 该 使 用 中 间 件 。 为 此 ， 可 以 在 _init_ 方法 中 抛 出 django.core.excep- 
tions.MiddlewareNotUsed。 此 时 ，Django 会 从 中 间 件 列表 中 删除 那个 中 间 件 ， 如 果 DEBUG 的 值 为 True， 还 会 
在 django.request 日 志 记 录 器 中 记录 一 条 调试 消息 。 






































17.3.7 其 他 指导 方针 


。 中 间 件 类 无 需 继承 任何 类 。 


。 中 间 件 类 可 以 放 在 Python 路 径 中 的 任何 位 置 。 对 Django 来 说 ， 只 需 在 MIDDLEWARE_CLASSES 设置 中 列 
出 中 间 件 类 的 路 径 。 


。 如 果 想 找 示例 ， 看 看 Django 自 带 的 中 间 件 。 


。 如 果 你 觉得 自己 编写 的 中 间 件 组 件 对 别人 可 能 也 有 用 ,贡献 到 社区 中 ! 让 我 们 知道 你 编写 了 中 间 件 ， 
我 们 会 考虑 要 不 要 把 它 添加 到 Django 中 。 































































































17.4 可 用 的 中 间 件 


17.4.1 缓存 中 间 件 


django.middleware.cache.UpdateCacheMiddleware 和 django.middleware.cache.FetchFromCacheMiddleware 



























































为 全 站 启用 缓存 。 启 用 这 两 个 中 间 件 后 ，Django 驱动 的 每 个 页 面 都 最 长 缓存 CACHE_MIDDLEWARE_SECONDS 所 定 
义 的 秒 数 。 参 见 第 16 章 。 


17.4.2 常用 中 间 件 
django.middleware.common.CommonMiddleware 


为 完美 主义 者 增添 几 分 便利 : 
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。 禁止 DISALLOWED_USER_AGENTS 设置 中 的 用 户 代理 访问 。 这 个 设置 的 值 是 编译 后 的 正则 表达 式 对 象 列 
表 。 

。 根据 APPEND_SLASH 和 PREPEND_NWW 设置 重 写 URL。 
APPEND_SLASH 设 为 True 时 ， 如 果 原 始 URL 不 以 斜 线 结尾 ， 而 且 在 URL 配置 中 找 不 到 ， 就 在 后 面 添加 
一 条 斜 线 ， 构 成 一 个 新 URL。 如 果 在 URL 配置 中 找 得 到 这 个 新 URL，Django 把 请 求 重 定向 到 新 
URL。 和 否则 ， 使 用 常规 方式 处 理 原 URL。 人 例如， 如果 没 有 匹配 foo.com/bar 的 URL 模式 ， 但 有 匹配 
foo.com/bar/ 的 模式 ，foo.com/bar 将 重 定向 到 foo.com/bar/。 
PREPEND_WNW 设 为 True 时 ， 前 面 没有 “www. ”的 URL 将 重 定向 到 带 “www.* 的 URL。 
这 两 个 设置 的 目的 是 规范 化 URL。 这 背后 的 思想 是 ， 每 个 URL 都 应 该 是 唯一 的 。 严 格 来 说 ， 
foo.com/bar 这 个 URL 与 foo.com/bar/ 是 有 区 别 的 ， 搜 索引 擎 索引 程序 会 将 其 视 为 不 同 的 URL， 所 以 
最 好 规范 化 URL。 

。 根据 USE_ETAGS 设置 处 理 ETag。USE_ETAGS 设 为 True 时 ，Django 会 计算 页 面 内 容 的 MD5 哈 希 值 ， 
于 设 定 Etag 首部 ， 而 且 还 会 适时 发 送 Not Modified 响应 。 















































CommonMiddleware.response_redirect class 





默认 为 HttpResponsePermanentRedirect。 可 以 继承 CommonMiddleware 类 ， 然 后 覆盖 这 个 属性 ， 自 定义 中 间 件 
以 何 种 方式 重 定向 。 





django.middleware.common.BrokenLinkEmailsMiddleware 


遇 到 死 链 时 发 送 邮 件 通知 MANAGERS。 


17.4.3 GZip 中 间 件 


安全 研究 人 员 近 期 发 现 ， 使 用 压缩 技术 (包括 GZipMiddleware) 的 网 站 有 些 漏洞 ， 容 易 受到 攻 
击 。 攻 击 者 可 以 利用 这 些 漏洞 攻破 Django 的 CSRF 防线 。 使 用 GZipMiddleware 之 前 要 谨慎 考 
虑 ， 以 免 受 到 这 些 攻击 。 哪 怕 有 一 点 述 疑 ， 都 不 应 该 使 用 GZipMiddleware。 详 情 参 见 breachat- 
tack.com 。 
为 支持 GZip 压缩 的 浏览 器 (所 有 现代 的 浏览 器 ) 压缩 内 容 。 
这 个 中 间 件 应 该 放 在 任何 需要 读 写 响应 主体 的 中 间 件 之 前 ， 保 证 在 所 有 读 写 操作 之 后 压缩 。 
满足 下 述 任何 一 个 条 件 时 不 再 压缩 内 容 : 
。 主体 内 容 少 于 200 字 节 。 
。 响应 已 经 设 定 了 Content-Encoding 首部 。 
。 (浏览 器 ) 发 送 的 Accept-Encoding 请 求 首 部 中 不 包含 gzip。 


可 以 使 用 gzip_page() 装饰 器 在 具体 的 视图 上 应 用 GZip 压缩 。 


17.4.4 条 件 GET 请 求 中 间 件 


django.middleware.http.ConditionalGetMiddleware 





处 理 条 件 GET 请 求 。 如 果 响 应 有 ETag 或 Last-Modified 首部 ， 而 且 请 求 有 If-None-Match 或 If-Modified- 
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Since 首部 ， 把 响应 替换 成 HttpResponseNotModified 对 象 。 
还 设 定 Date 和 Content-Length 响应 首部 。 
17.4.5 区 域 设置 中 间 件 


django.middleware. locale.LocaleMiddleware 


根据 请 求 中 的 数据 选择 语言 ， 为 用 户 提供 定制 内 容 。 参 见 第 18 章 。 





LocaleMiddleware.response_redirect class 


默认 为 HttpResponseRedirect。 可 以 继承 LocaleMiddleware 类 ， 然 后 覆盖 这 个 属性 ， 自 定义 中 间 件 以 何 种 方 
式 重 定向 。 


17.4.6 消息 中 间 件 
django.contrib.messages.middleware.MessageMiddleware 


提供 基于 cookie 和 会 话 的 消息 支持 。 参 见 消息 文档 。 





17.4.7 安全 中 间 件 


如 果 部 署 环境 允许 ， 通 常 最 好 让 前 端 Web 服务 器 负责 执行 securitytddteware 提供 的 功能 。 
这 样 ， 不 由 Django 伺服 的 请 求 例 如 静态 媒体 文件 或 用 户 上 传 的 文件 ) 与 由 Django 伺服 的 请 
求 具有 相同 的 保护 措施 。 


django.middleware.security.SecurityMiddleware 为 请 求 -响应 循环 增加 了 几 项 安全 措施 。SecurityMiddleware 
的 做 法 是 向 浏览 器 发 送 几 个 特殊 的 首部 。 每 个 首部 都 可 以 在 设置 中 单独 启用 或 禁 























o 


HTTP 强制 安全 传输 技术 

设置 : 
。 SECURE_HSTS_INCLUDE_SUBDOMAINS 
。 SECURE_HSTS_SECONDS 

如 果 你 的 网 站 只 人 允许 通过 HITPS 访问 ， 可 以 设 定 Strict-Transport-Security 首部 ， 告 知 现代 的 浏览 器 (在 


指定 的 时 长 内 ) 拒绝 通过 不 安全 的 连接 访问 你 的 域名 。 这 样 能 降低 受到 非 SSL 中 间 人 攻击 (man-in-the-mid- 
dle，MITM) 的 风险 。 





如 果 把 SECURE_HSTS_SECONDS 设 为 非 零 整 数值 ，SecurityMitddLeware 会 为 所 有 HTTPS 响应 设 定 这 个 首部 。 


启用 HSTS 时 ， 最 好 先 用 小 值 测试 一 下 ， 例 如 SECURE_HSTS_SECONDS = 3600 (一 小 时 ) 。Web 浏览 器 发 现 有 
HSTS 首部 时 ， 会 在 指定 的 时 长 内 拒绝 通过 非 安全 的 连接 (使 用 HITP) 访问 你 的 域名 。 


确认 所 有 静态 资源 都 能 通过 安全 的 连接 伺服 之 后 ( 即 HSTS 没有 导致 任何 问题 ) ， 最 好 增 大 这 个 值 (经 常设 
为 31536000 秒 ， 即 一 年 ) ， 让 不 常 访问 的 访客 受到 保护 。 
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此 外 ， 如 果 把 SECURE_HSTS_INCLUDE_SUBDOMAINS 设 为 True，SecurityMiddleware 会 在 Strict-Transport-Secu- 
rity 首部 中 加 上 includesubDomaiins 标签 。 推 荐 这 样 做 (假设 所 有 子 域名 也 都 只 能 通过 HITPS 访问 ) ,否则 
仍然 能 通过 不 安全 的 连接 访问 子 域名 。 


HSTS 策略 应 用 于 整个 域名 ， 而 不 只 是 设 定 Strict-Transport-Security 首部 的 那个 URL。 
此 ， 仅 当 整 个 域名 都 通过 HTTPS 伺服 时 才 应 该 使 用 HSTS。 严 格 遵 守 HSTS 首部 的 浏览 器 遇 到 
过 期 的 、 自 签名 的 或 无 效 的 SSL 证 书 时 拒绝 用 户 跳 过 提醒 ， 不 允许 继续 访问 。 使 用 HSTS 时 ， 
要 确保 证 书 始终 有 效 ! 





X-Content-Type-Options: nosniff 
设置 : 
® SECURE CONTENT_TYPE_ NOSNIFF 


某 些 浏览 器 会 尝试 猜测 静态 资源 的 内 容 类 型 ， 继 而 覆盖 Content-Type 首部 。 这 样 虽 然 可 以 帮助 未 正确 配置 的 
服务 器 显示 网 站 ， 但 是 也 存在 安全 隐患 。 


如 果 网 站 人 允许 用 户 上 传 文件 ， 恶 意 用 户 可 以 上 传 精心 制作 的 文件 ， 你 以 为 那 是 无 害 的 ， 其 实 却 会 被 浏览 器 解 
释 为 HTML 或 JavaScript。 











为 了 防止 浏览 右 猜 测 内 容 类 型 ， 强 制 始终 使 用 Content-Type 首部 指定 的 类 型 ， 设 定 X-Content-Type-Options: 
nosniff 首部 。SECURE_CONTENT_TYPE_NOSNIFF 设 为 True 时 ，SecurityMiddleware 为 所 有 响应 设 定 这 个 首部 。 





注意 ， 多 数 情 况 下 ， 用 户 上 传 的 文件 不 由 Django 伺服 ， 此 时 ， 这 个 设置 帮 不 上 什么 忙 。 例 如 ， 如 果 ME- 
DIA_URL 直接 由 前 端 Web 服务 器 (Nginx、Apache， 等 等 ) 伺服 ， 应 该 在 那里 设 定 这 个 首部 。 


另 一 方面 ， 如 果 需 要 核对 权限 后 才能 下 载 文件 ， 而 且 无 法 在 Web 服务 器 中 设 定 这 个 首部 ， 可 以 使 用 这 个 设 
置 。 








X-XSS-Protection 
设置 : 
® SECURE BROWSER XSS_FILTER 


有 些 浏览 器 能 屏蔽 像 是 XSS 攻击 的 内 容 。 为 此 ， 浏 览 器 在 页 面 的 GET 或 POST 参数 中 查找 有 没有 JavaScript 
内 容 。 如 果 服 务 器 的 响应 中 重 放 了 JavaScript， 浏 览 器 不 会 泻 染 ， 而 是 显示 一 个 错误 页 面 。 


X-XSS-Protection 首部 用 于 控制 这 种 XSS 过 滤 功 能 。 


























若 想 启用 浏览 器 的 XSS 过 滤 功 能 ， 强 制 始终 屏蔽 可 疑 的 XSS 攻击 ， 设 定 X-XSS-Protection: 1; mode=block 
首部 。SECURE_BROWSER_XSS_FILTER 设 为 True 时 ，SecurityMiddleware 为 所 有 响应 设 定 这 个 首部 。 


浏览 器 的 XSS 过 滤 功 能 是 个 有 用 的 防御 措施 ， 但 是 不 能 完全 依靠 它 。 它 不 能 侦 测 到 全 部 XSS 
攻击 ， 而 且 也 不 是 所 有 浏览 器 都 支持 这 个 首部 。 一 定 要 验证 所 有 输入 ， 避 免 受到 XSS 攻击 。 
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SSL 重 定向 
设置 : 
。 SECURE_REDIRECT_EXEMPT 


。 SECURE_SSL_HOST 


。 SECURE_SSL_REDIRECT 





本 





如 果 你 的 网 站 同时 支持 HITP 和 HTTPS， 多 数 用 户 最 终 默 认 用 的 是 不 安全 的 连接 。 为 了 增强 安全 ， 应 该 把 所 


HTTP 连接 重 定向 到 HITPS 。 




















如 果 把 SECURE_SSL_REDIRECT 设 为 True，SecurityMiddleware 会 把 所 有 HTTP 连接 永久 重 定向 (HTTP 301) 
到 HTTPS 。 








出 于 性 能 上 的 考虑 ， 最 好 在 Django 之 外 ， 在 负载 均衡 程序 或 反 向 代理 服务 器 (如 Nginx) 中 重 定向 。 不 便 配 
置 部 署 环境 时 才 应 该 使 用 SECURE_SSL_REDIRECT 设置 。 


























如 果 SECURE_SSL_H0ST 设置 不 为 空 值 ， 所 有 重 定向 都 指向 那个 主机 ， 而 非 最 初 请 求 的 主机 。 

















如 果 网 站 中 有 部 分 页 面 要 通过 HTTP 访问 ， 不 重 定向 到 HTTPS， 可 以 在 SECURE_REDIRECT_EXEMPT 设置 中 列 出 
匹配 那些 URL 的 正则 表达 式 。 


1 果 应 用 程序 部 署 在 负载 均衡 程序 或 反 向 代理 服务 器 之 后 ， 而 且 Django 好 像 无 法 辨识 请 求 是 不 是 安全 的 ， 可 
E 需 要 设 定 SECURE_PROXY_SSL_HEADER 首部 。 


















































17.4.8 会 话 中 间 件 


django.contrib.sessions.middleware.SessionMiddleware 





启用 会 话 支持 。 详 情 参见 第 15 章 。 





17.4.9 网 站 中 间 件 


django.contrib. sites.middleware.CurrentSiteMiddleware 





在 每 个 人 站 HttpRequest 对 象 中 添加 表示 当前 网 站 的 site 属性 。 详 情 参见 网 站 文档 。 











17.4.10 身份 验证 中 间 件 


django.contrib.auth.middleware 提供 三 个 在 身份 验证 过 程 中 使 用 的 中 间 件 : 








。 *.AuthenticationMiddleware: 在 每 个 人 站 HttpRequest 对 象 中 添加 表示 当前 已 登录 用 户 的 user 属性 。 
。 *.RemoteUserMiddleware: 利用 Web 服务 器 提供 的 身份 验证 。 


。 *.SessionAuthenticationMiddleware: 修改 密码 后 让 用 户 的 会 话 失 效 。 在 MIDDLEWARE_CLASSES 中 ， 这 
个 中 间 件 必须 出 现在 *.AuthenticationMiddleware 后 面 。 










































































关于 在 Django 中 验证 用 户 身 份 的 详细 说 明 ， 参 见 第 11 章 。 





17.4.11 CSRF 防护 中 间 件 


django.middleware.csrf.CsrfViewMiddleware 
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为 POST 表单 添加 隐藏 的 表 身 















































字段 ， 并 且 检 查 请 求 中 有 没有 正确 的 值 ， 防 范 跨 站 请 求 伪造 (Cross Site Request 














Forgery，CSRF) 。 关 于 CSRF 防护 的 详细 说 明 ， 参 见 第 19 章 。 


17.4.12 X-FRAME-OPTIONS 中 间 件 


django.middleware.clickjacking.XFrameOptionsMiddleware 


通过 X-Frame-0ptions 首部 防范 点 击 劫持 (clickjacking) 。 


17.5 中 间 件 的 顺序 





表 17-1 简要 说 明 一 些 Django 中 间 件 类 的 顺序 。 


表 17-1， 中 间 件 类 的 顺序 





类 


说 明 





UpdateCacheMiddleware 


GZipMiddleware 


ConditionalGetMiddleware 


SessionMiddleware 


LocaleMiddleware 


CommonMiddleware 


CsrfViewMiddleware 


AuthenticationMiddleware 


MessageMiddleware 


FetchFromCacheMiddleware 


FlatpageFallbackMiddleware 应 该 放 在 靠近 


RedirectFallbackMiddleware 应 该 放 在 靠近 


在 修改 Vary 首部 的 中 间 件 (SessionMiddleware、 


GZipMiddleware、LocaleMiddleware) 前 面 。 


在 任何 可 能 修改 或 使 用 响应 主体 的 中 间 件 前 面 。 在 
UpdateCacheMiddleware 后 面 ， 因 为 要 修改 Vary 首部 。 






























































在 CommonMiddleware 前 面 ， 因 为 设 定 USE_ETAGS = True 时 ， 
要 使 用 Etag 首部 。 


在 UpdateCacheMiddLeware 后 面 ， 因 为 要 修改 Vary 首部 。 


在 前 部 ，SessionMiddleware (使 用 会 话 数据 ) 和 
CacheMiddleware (修改 Vary 首部 ) 后 面 。 


在 任何 可 能 修改 首部 的 中 间 件 前 面 (要 计算 Etag) 。 在 

GzipMiddleware 后 面 ， 因 为 不 为 压缩 的 内 容 计 算 Etag。 靠 近 
顶部 ， 因 为 APPEND_SLASH 或 PREPEND_WWW 设 为 True 时 要 重 定 
向 [ed 


在 任何 假定 已 经 防范 了 CSRF 攻击 的 视图 中 间 件 前 面 。 
在 SessionMiddleware 后 面 ， 因 为 要 使 用 会 话 存储 器 。 


在 SessionMiddleware 后 面 ， 这 样 才能 使 用 基于 会 话 的 存储 
串 。 


在 任何 修改 vary 首部 的 中 间 件 后 面 ， 因 为 创建 缓存 哈 希 键 时 
要 从 那个 首部 中 选 一 个 值 。 


基部 的 位 置 ， 做 最 后 一 搏 。 
基部 的 位 置 ， 做 最 后 一 搏 。 


















































































































































17.6 接 下 来 


下 一 章 讨论 Django 对 国际 化 的 支持 。 
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Django 最 初 在 美国 正中 开发 ， 我 说 的 是 真 的， 堪萨斯 州 劳伦斯 市 离 美 国 大 陆 的 地 理 中 心 不 到 40 英里 。 与 多 
数 开源 项 目 一 样 ，Django 社区 不 断 发 展 ， 吸 引 了 来 自 世 界 各 地 的 人 。 随 着 Django 社区 不 断 多 元 化 ， 国 际 化 
(internationalization) 和 本 地 化 (localization) 变 得 越 来 越 重 要 。 



































Django 自身 已 经 做 了 全 面 国际 化 ， 所 有 字符 串 都 标记 为 可 翻译 的 ， 


























而 且 还 有 控制 本 地 化 输出 (如 日 斯 和 时 


























间 ) 的 设置 。Django 自 带 了 超过 50 种 本 地 化 文件 。 如 果 你 的 母语 不 是 英语 ， 很 有 可 能 Django 已 经 为 你 的 语 

















言 提 供 了 翻译 。 

















Django 自身 使 用 的 国际 化 框架 也 可 用 于 本 地 化 你 的 代码 和 模板 。 

















18.1 定义 







































































18.1.1 国际 化 








因为 很 多 开发 者 没有 正确 理解 国际 化 和 本 地 化 的 真正 意义 ， 所 以 我 们 先 下 几 个 定义 。 





指 为 任何 区 域 设 置 提供 支持 的 程序 设计 过 程 。 这 个 过 程 通常 由 软件 开发 者 处 理 。 国 际 化 包括 标记 可 翻译 的 文 
本 (例如 UI 元 素 和 错误 消息 ) ， 抽象 日 期 和 时 间 的 显示 方式 ， 兼 顾 不 同 的 区 域 标准 ， 支 持 不 同 的 时 区 ， 以 







































































尾 的 N 之 间 的 18 个 字母 。) 


18.1.2 本 地 化 


指 把 国际 化 的 程序 翻译 成 特定 区 域 的 语言 。 这 个 过 程 通常 由 翻译 人 员 人 处 理 。 本 地 化 有 时 缩写 为 L10N，。 














及 在 代码 中 不 对 用 户 的 区 域 位 置 做 任何 假设 。 国 际 化 经 常 缩写 为 118N。 (数字 18 表示 省 略 了 开头 的 1 和 末 












































处 理 语言 时 还 会 用 到 一 些 其 他 术语 ; 





区 域 设置 名 称 






































LL 形式 的 语言 规范 码 ， 或 者 tt_cc 形式 的 语言 和 国家 规范 码 。 例 如 : it、de_AT、es、pt_BR。 语 言 部 分 始 





终 小 写 ， 


语言 代码 


表示 语言 的 名 称 。 浏 览 器 在 Accept-Language 首部 中 使 
es、pt-br。 语 言 代码 一 般 使 用 小 写字 母 表示 ， 但 是 Accept-Language 首部 不 区 分 大 小 写 。 分 隔 符 是 一 个 连 


字符 。 


消息 文件 


表示 一 种 语言 的 纯 文本 文件 ， 包 含 所 有 可 翻译 的 字符 串 ， 以 及 目 


.po。 


翻译 字符 串 














国家 部 分 始终 大 写 。 中 间 以 一 个 下 划 线 分 开 。 















































j 这 种 格式 指定 接受 的 语言 。 例 如 : it、de-at、 























可 以 翻译 的 文本 串 。 


标语 言 的 表述 。 消 息 文件 的 扩展 名 是 
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格式 文件 





定义 目标 区 域 设置 所 


18.2 翻译 


若 想 翻 译 


诉 Django， 把 文本 翻译 


译 的 ， 系 统 只 


完毕 后 还 要 编译 。 这 个 过 程 使 用 GNU gettext 工 





最 后 ，Django 动态 地 把 Web 应 























Django 项 目 ， 要 在 Python 代码 和 模板 








对 成 终端 用 




















其 实 ，Django 在 这 个 过 程 中 做 了 两 件 事 : 


。 让 开发 者 和 模板 编写 人 员 指 定 


应 用 中 的 








数据 格式 的 Python 模块 。 


添加 少量 的 钩子 。 
户 的 语言 《如果 消息 文件 中 有 文本 的 翻译 ) 。 
能 翻译 它 知道 如 何 翻 译 的 字符 串 。 


然后 ，Django 把 翻译 字符 串 提取 到 一 个 消息 文件 中 。 翻 译 人 员 在 这 个 文件 中 使 

















具 集 。 

















1 翻译 成 用 户 选择 的 语言 。 








。 根据 用 户 的 语言 偏好 设置 翻译 Web 


Django 的 国际 化 钩子 默认 启用， 这 意味 着 在 框架 的 某 些 位 置 要 处 理 国际 化 ， 
化 ， 应 该 花 两 秒 钟 在 设置 文件 

















MY. 




















这 些 钩子 叫做 翻译 字符 串 ， 其 








作用 是 告 





尔 要 负责 把 字符 串 标记 为 可 翻 
































那些 地 方 应 该 翻译 。 
程序 。 























j 目标 语言 翻译 字符 串 。 














去 一 些 消耗 。 还 有 











18.3 国际 化 Python 代码 


18.3.1 标准 的 翻译 函数 





翻译 字符 





Python 标准 库 中 的 gettext 模块 在 全 局 命名 空 








么 做 ， 原 因 如 下 : 


1. ugettext() 对 国际 字符 集 


翻译 函数 。 








2. 在 Python 的 交互 式 shell 和 doctest 中 


行为 有 影响 。 


下 述 示例 把 “Welcome to my site." 标 记 为 翻译 字符 














把 ugettext() 导入 为 _() 能 





串 使 用 ugettext() 函数 指定 。 为 了 写 起 


Pp 设 定 USE_I18N = False。 这 样 ，Django 会 做 些 优化 ， 
个 与 此 无 关 的 设置 ，USE_L10N， 








它 用 于 探 





方便 ， 可 以 











翻译 


























因此 有 些 消耗 。 如 果 不 使 用 国际 
不 加 载 国际 化 机 制 ， 省 
草 是 和 否 让 Django 本 地 化 格式 。 
导入 为 别名 _。 








间 中 安装 _()， 作 为 gettext() 的 别名 。 在 Django 中 不 应 该 这 








站 
PF : 


from django.utils.translation import ugettext as _ 


from django.http import HttpResponse 


def my_view(request): 


output = 


_("Welcome to my site.") 


return HttpResponse(output) 





当然 ， 也 可 以 不 使 用 别名 。 下 述 示例 与 之 等 


旭 





效 : 


from django.utils.translation import ugettext 


， 下 划 线 (_) 表示 前 一 个 结果 。 如 果 注 册 全 
避免 这 个 问题 。 


间 之 外 促使 开发 者 思考 哪个 才 是 





(Unicode) 的 支持 比 gettext() 好 。 有 时 ， 在 特定 的 文件 中 应 该 把 uget- 
text_Lazy() 作为 默认 的 翻译 方法 。 把 _() 排除 在 全 局 命名 空 


最 恰当 的 


局 的 _() 函数 ， 对 此 
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from django.http import HttpResponse 


def my_view(request): 


output = ugettext("Welcome to my site.") 
return HttpResponse(output) 


通过 计算 得 到 的 值 也 能 翻译 。 下 述 示例 与 之 等 效 ; 





def my_view(request): 


words = ['Welcome', 'to', 'my', 'site.'] 


output = _(' '.join(words)) 
return HttpResponse(output) 


变量 也 一 样 能 翻译 。 下 述 示例 与 之 等 效 : 





def my_view(request): 


sentence = 'Welcome to my site.’ 
output = _(sentence) 
return HttpResponse(output) 





( 像 上 卫 








j 这 样 翻译 变量 和 计算 得 到 的 值 有 个 问题 : Django 检测 翻译 字符 串 的 工 











无 法 找到 它们 。makemessages 在 后 文 详 述 。) 
传 给 _() 或 ugettext() 的 字符 串 可 以 带 有 占 位 符 ， 通 过 Python 标准 的 具名 字符 串 内 插 句 法 指定 。 例 如 : 

















具 django-admin makemessages 























def my_view(request, m, d): 
output = _('Today is %(month)s %(day)s.') % {'month': m, 'day': d} 


return HttpResponse(output) 


这 样 便于 针对 特定 的 语言 重新 排列 占 位 文本 。 例 如 ， 英 语 翻 译 可 能 是 “Today is 
译 则 是 “Hoy es 26 de Noviembre”， 即 月 和 日 的 位 置 对 调 了 。 


鉴于 此 ， 

















November 26.”， 而 西班牙 语 翻 





有 多 个 参数 时 应 该 使 用 具名 内 播 占 位 符 (如 %(day)s) ， 不 能 使 用 位 置 内 播 占 位 符 〈 如 %s 或 %d) 。 
如 若 不 然 ， 翻 译 时 无 法 重新 排列 占 位 文本 。 














18.3.2 给 翻译 人 员 看 的 注释 


如 果 想 对 翻译 人 员 解 释 可 翻译 的 字符 串 ， 可 以 在 翻译 字符 串 前 甸 


例如 : 




















def my_view(request): 


在 得 到 的 .po 文件 中 ， 这 个 注释 会 与 要 翻译 的 内 容 放 在 一 起 ， 而 且 多 数 翻 译 工 


# Translators: This message appears on the home page only 
output = ugettext("Welcome to my site.") 





| 一 行 添加 一 个 以 TransLators 开头 的 注释 ， 
































下 面 是 前 例 得 到 的 .po 文件 中 的 相应 片段 : 


#. TransLators: This message appears on the home page only 
# path/to/python/file.py:123 
msgid "NeLcome to my site." 


msgstr 


在 模板 中 也 可 以 这 么 做 ,详情 参见 18.4.4 。 


具 都 能 把 它 显 示 出 来 。 
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18.3.3 把 字符 串 标 记 为 暂时 无 需 翻译 





django.utils.translation.ugettext_noop() 范 数 的 作用 是 把 字符 串 标 记 为 翻译 字符 串 ， 但 是 暂时 不 翻译 ， 而 


是 从 变量 中 翻译 。 











要 在 系统 或 用 户 之 间 交 换 的 不 变 字符 串 〈 例 如 数据 库 中 的 字符 串 ) 应 该 存储 在 源 语言 中 ， 而 且 应 该 尽量 推迟 




















翻译 〈 例 如 在 呈现 给 用 户 时 ) ， 此 时 就 可 以 使 用 这 个 函数 。 








18.3.4 复数 变形 

















NS 


django.utiLs.transLation.ungettext() 国 数 用 于 指定 消息 的 复数 形式 。 





YY 








ungettext 接受 三 个 参数 : 翻译 字符 串 的 单数 形式 ， 翻 译 字符 串 的 复数 形式 ， 以 及 对 象 的 数量 。 





























如 果 想 让 Django 应 用 程序 可 以 本 地 化 到 比 英 语 的 复数 变形 复杂 的 语言 (英语 有 两 种 
只 要 超过 一 个 都 用 "objects") ， 要 使 用 这 个 函数 。 





例如 : 


from django.utils.translation import ungettext 
from django.http import HttpResponse 


def hello world(request, count): 

page = ungettext( 
'there is %(count)d object', 
'there are %(count)d objects ' ， 
count 
)%{ 

'count': count, 

} 

return HttpResponse(page) 


这 里 ， 对 象 的 数量 通过 count 变量 传 给 翻译 字符 串 。 




















形式 ， 单 数 是 “object”， 


注意 ， 不 同 语言 的 复数 变形 方式 不 同 ， 不 能 始终 与 “1 比较。 下 述 代码 看 似 完备 ， 但 是 在 某 些 语言 中 会 得 到 错 


误 的 结果 : 


from django.utils.translation import ungettext 
from myapp.models import Report 


count = Report.objects.count() 
uf EU == 
name = Report._meta.verbose_name 
else: 
name = Report._meta.verbose_name_plural 


text = ungettext( 
'There is %(count)d %(name)s available.', 
'There are %(count)d %(name)s available.', 
count 
)%{ 
'count': count, 
'name': name 
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别 试图 自己 实现 单 复数 变形 逻辑 ， 肯 定 会 出 错 的 。 看 看 下 面 这 个 例子 : 





text = Ungettext( 
'There is %(count)d %(name)s object available.', 
'There are %(count)d %(name)s objects available.', 
count 
)%{ 
"count ' : count, 
name ' : Report._meta.verbose_name, 


} 


使 用 ungettext() 时 ， 两 个 文本 串 中 要 内 插 的 变量 要 使 用 相同 的 名 称 。 注 意 ， 在 上 述 示 例 中 ， 两 个 翻译 字符 
串 中 使 用 的 都 是 name 变量 。 下 述 示例 除了 在 某 些 语言 中 得 不 到 正确 的 结果 之 外 ， 本 身 就 是 错 的 : 



































text = ungettext( 

'There is %(count)d %(name)s available.', 

'There are %(count)d %(plural_name)s available.', 

count 

几时 这 
"count ' : Report.objects.count() ， 
name ' : Report._meta.verbose_name, 
'plural_name': Report._meta.verbose_ name_plural 


} 
运行 django-admin compilemessages 命令 时 会 得 到 下 述 错误 : 


a format specification for argument 'name', as in 'msgstr[0]', doesn't exist tin 'msgid' 


18.3.5 语 境 标记 




















9 些 单词 有 不 同 的 意思 ， 例 如 英语 中 的 “May”， 它 既 指 一 个 月 份 ， 也 表示 一 个 动词 。 为 了 让 翻译 人 员 根 据 语 
境 正确 翻译 多 义 词 ， 可 以 使 用 django.utils.translation.pgettext() 函数 ， 有 复数 变形 的 字符 串 则 使 用 


django.utils.translation.npgettext() 函数 。 这 两 个 函数 的 第 一 个 参数 都 是 说 明 语 境 的 字符 串 。 





















































在 得 到 的 .po 文件 中 ， 相 同 的 字符 串 用 语 境 标记 了 多 少 次 就 会 出 现 多 少 次 语 境 在 msgctxt 行 里) ， 以 便 翻 
译 人 员 为 各 个 语 境 提供 翻译 。 


例如 : 





from django.utils.translation import pgettext 


month = pgettext("month name", "May") 
或 者 : 


from django.db import models 
from django.utils.translation import pgettext_Lazy 


class MyThing(models .Model): 
name = modeLs.CharFieLd(heLp_text=pgettext_Lazy( 
'help text for MyThing model', 'This is the help text')) 


在 .po 文件 中 是 这 样 的 : 
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msgctxt "month name" 
msgid "May" 


msgstr 


模板 标签 trans 和 blocktrans 也 支持 语 境 标记 。 


18.3.6 情 性 翻译 


这 


定义 模型 、 表 单 和 模型 表单 时 都 是 如 此 ， 因 为 Django 以 类 级 属性 实现 相应 的 字段 。 鉴 于 此 ， 在 下 述 各 种 情 
中 一 定 要 使 用 惰性 翻译 。 

































































想 懈 性 翻译 字符 串 ， 即 在 访问 值 时 翻译 ， 而 不 是 调用 翻译 函数 时 翻译 ， 使 用 django.uttitLs.transLation 中 
译 函 数 的 惰性 版 本 (名 称 以 Lazy 结尾 ) 。 
些 函 数 存储 字符 串 的 惰性 引用 ， 而 不 是 真正 的 翻译 。 在 字符 串 上 下 文中 使 用 字符 串 时 才 会 翻译 ， 例 如 泻 染 
板 时 。 

这 其 实 就 相当 于 调用 模块 加 载 时 执行 的 代码 路 径 里 的 函数 。 



































SS 




















模型 字段 和 关系 


例如 ， 要 像 下 面 这 样 翻译 name 字段 的 说 明文 本 : 


from django.db import models 
from django.utils.translation import ugettext lazy as _ 


class MyThing(models .Model): 
name = models.CharField(help_ text=_('This is the help text')) 


可 以 使 用 verbose_name 参数 把 ForeignKey 和 ManyToManyField 或 OneToOneField 关系 的 名 称 标记 为 可 翻译 


的 : 


class MyThing(models.Model): 
kind = models.ForeignKey(ThingKind, related name='kinds', verbose_name=_('kind')) 











这 里 设 定 的 verbose_name 是 小 写 形式 。 类 似 地 ， 关 系 的 详细 名 称 也 应 该 使 用 小 写 形式 ， 因 为 Django 在 需要 
时 会 自动 把 首 字母 变 成 大 写 。 











模型 的 详细 名 称 

















建议 始终 明确 为 模型 的 类 名 设 定 verbose_name 和 verbose_nane_plural， 不 要 依赖 默认 以 英语 为 中 心 的 生成 方 
式 ， 














因为 那样 得 到 的 结果 有 时 很 可 笑 。 


from django.db import models 
from django.utils.translation import ugettext lazy as _ 


class MyThing(models.Model): 
name = models.CharField(_('name'), help text= _('This is the help text')) 


class Meta: 
verbose name = _('my thing') 
verbose_name_pLuraL = _('my things') 
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模型 方法 的 short_description 属性 值 





可 以 通过 short_description 属性 为 模型 方法 提供 翻译 ， 供 Django 和 管理 后 台 使 用 : 











from django.db import models 
from django.utils.translation import ugettext lazy as _ 


class MyThing(models.Model): 
kind = models.ForeignKey(ThingKind, related name='kinds', verbose name=_('kind')) 


def is mouse(self): 


return self.kind.type == MOUSE_TYPE 
is mouse.short description = _('Is it a mouse?') 


18.3.7 处 理 情 性 翻译 对 象 

















ugettext_lazy() 调用 得 到 的 结果 可 以 在 任何 能 使 用 Unicode 字符 串 (类 型 为 unicode 的 对 象 ) 的 Python 代码 
中 使 用 。 但 是 不 能 在 期 待 字 节 字 符 串 〈str 对 象 ) 的 地 方 使 用 ， 因 为 ugettext_lazy() 返回 的 对 象 不 知道 怎么 
把 自己 转换 成 字 节 字符 串 。 此 外 ， 也 不 能 在 字 节 字符 串 中 使 用 Unicode 字符 串 ， 这 与 Python 的 行为 是 一 致 
的 。 例 如 








# 可 以 这 么 做 : 在 Unicode 字符 串 中 放置 一 个 Unicode 代理 
"Hello %s" % ugettext_Lazy("peopLe'") 


# 不 能 这 么 做 ， 因 为 不 能 在 字 节 字符 囊 中 插入 Unicode 对 象 
# (也 不 能 放置 Unicode 代理 ) 
b"Hello %s" % ugettext_ lazy("people") 


如 果 看 到 类 似 "hello <django.utils.functional..>" 这 样 的 输出 ， 说 明 你 把 ugettext_Lazy() 的 结果 插入 字 节 
字符 串 中 了 ， 也 就 是 代码 有 问题 。 


如 果 不 想 输 入 ugettext_Lazy 这 么 长 的 名 称 ， 可 以 像 下 面 这 样 创建 别名 _ (下 划 线 ) : 





from django.db import models 
from django.utils.translation import ugettext lazy as _ 


class MyThing(models.Model): 
name = models.CharField(help text=_('This is the help text')) 


Ud 





经 常 使 用 ugettext_lazy() 和 ungettext_lazy() 标记 模型 和 实用 函数 中 的 字符 串 。 在 代码 中 处 理 这 些 字符 是 
时 要 小 心 ， 不 要 将 其 转换 成 字符 串 ， 因 为 应 该 尽量 延 后 转换 操作 (这 样 才 能 让 区 域 设置 起 作用 ) 。 鉴 于 此 ， 
有 必要 使 用 接 下 来 说 明 的 辅助 函数 。 

































































惰性 翻译 和 复数 变形 





使 用 惰性 翻译 函数 〈[u]n[p]gettext_Lazy) 处 理 字符 串 的 复数 形式 时 ， 在 定义 字符 串 之 时 一 般 不 知道 number 
参数 的 值 。 此 时 ， 人 允许 通过 键 名 指定 number 参数 。 这 样 ， 内 插 字符 串 时 会 在 字典 的 那个 键 名 下 查找 number 
的 值 。 例 如 : 








from django import forms 
from django.utils.translation import ugettext_lazy 


class MyForm(forms.Form): 
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error_message = Ungettext_Lazy("You only provided %(num)d 
argument"，"You only provided %(num)d arguments", 'num') 


def clean(self): 
# ... 
if error: 
raise forms.ValidationError(self.error_message % 
{'num': number}) 





如 果 字 符 串 中 只 有 一 个 匿名 占 位 符 ， 可 以 直接 内 插 number 参数 : 





class MyForm(forms .Form) : 
error_message = Ungettext_Lazy("You provided %d argument", 
"You provided %d arguments") 


def clean(self): 
if error: 
raise forms.ValidationError(self.error_message % number) 


连接 字符 串 ，string_concat() 

















在 包含 惰性 翻译 对 象 的 列表 上 不 能 使 用 Python 标准 的 方式 连接 字符 串 ('' .join([..])) ， 而 要 使 用 djan- 
go.utils.translation.string_concat() 函数 。 这 个 函数 创建 一 个 惰性 对 象 ， 把 内 容 拼 接 起 来 ， 在 字符 串 中 插 
人 结果 时 才 将 其 转换 成 字符 串 。 例 如 : 


























from django.utils.translation import string_concat 
from django.utils.translation import ugettext_ lazy 
WE 

name = ugettext_lazy('John Lennon') 

instrument = ugettext lazy('guitar') 


result = string_concat(name, ，instrument) 























Ud 


这 里 ， 仅 当 在 字符 串 中 使 用 result 时 (通常 是 在 泻 染 模板 时 ) 才 把 是 








I 


的 惰性 翻译 转换 成 字符 串 。 














在 其 他 想 延迟 翻译 的 地 方 使 用 惰性 翻译 字符 串 





在 其 他 地 方 ， 如 果 想 延迟 翻译 ， 但 是 要 把 可 翻译 的 字符 串 作 为 参数 传 给 别 的 函数 ， 可 以 使 用 lazy 包装 。 例 
如 : 


from django.utils import six # 兼容 Python 3 

from django.utils.functional import lazy 

from django.utils.safestring import mark_safe 

from django.utils.translation import ugettext lazy as _ 


mark_safe_lazy = lazy(mark_safe, six.text_type) 














然后 这 么 用 : 








Lazy_string = mark_safe lazy(_("<p>My <strong>string!</strong></p>")) 
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18.3.8 语言 的 本 地 化 名 称 


get_language_info() 函数 提供 关于 语言 的 详细 信息 : 


name 和 name_local 键 的 值 分 别 是 语言 的 英文 名 和 在 目标 语言 中 的 名 称 。 仪 当 是 双向 书写 的 语言 时 ，bidi 键 


>>> from django.utils.translation import get_Language_info 
>>> li = get_language_info('de') 

>>> print(li['name'], li['name_local'], li['bidi']) 

German Deutsch False 











的 值 才 为 True。 


语言 信息 在 django.conf.locale 模块 中 。 在 模板 代码 中 也 能 以 类 似 的 方式 访问 这 些 信息 。 详 情 参见 下 文 。 














18.4 国际 化 模板 代码 





Django 模板 使 用 两 个 模板 标签 翻译 ， 而 且 与 在 Python 代码 中 的 句法 稍 有 不 同 。 若 想 在 模板 中 访问 那 两 个 标 


局 
签 























， 在 模板 顶部 写 上 {% load il8n }。 与 其 他 模板 标签 一 样 ， 每 个 需要 翻译 的 模板 都 要 有 这 人 么 一 个 Load 标 
签 ， 





即便 是 扩展 自己 经 加 载 了 il8n 标签 的 模板 也 是 如 此 。 





18.4.1 trans 模板 标签 


{% trans %} 模板 标签 既 能 用 于 翻译 不 变 的 字符 串 〈 放 在 单 引 号 或 双 引 号 中 ) ， 也 能 用 于 翻译 变量 的 内 容 : 








<title>{% trans "This is the title." %}</title> 
<title>{% trans myvar %}</title> 





如 果 指定 noop 选项 ， 会 查找 变量 ， 但 不 翻译 。 这 么 做 只 是 为 了 占 位 ， 而 把 翻译 留 到 未 来 式 个 时 刻 : 


ek 


位 





付 


<title>{% trans "myvar" noop %}</title> 


间 翻 译 在 背后 调用 ugettext() 函数 。 




















如 果 传 给 trans 标签 的 是 一 个 模板 变量 ， 在 运行 时 首先 把 变量 解析 成 字符 串 ， 然 后 在 消息 目录 中 查找 那个 字 
串 。 











在 {% trans %} 标签 中 ， 不 能 内 播 模板 变量 。 如 果 需 要 变量 中 的 字符 串 ( 占 位 符 ) ,使 用 {% blocktrans 


%}。 





如 果 想 获取 翻译 后 的 字符 串 ， 但 不 将 其 显示 出 来 ， 使 用 下 述 句法 : 


{% trans "This is the title" as the_title %} 














在 实际 运用 中 ， 如 果 需 要 在 多 个 地 方 使 用 翻译 后 的 字符 串 ， 或 者 作为 参数 传 给 别 的 模板 标签 或 过 滤器 ， 就 可 
以 这 么 做 : 








{% trans "starting point" as start %} 
{% trans "end point" as end %} 
{% trans "La Grande Boucle" as race %} 


<h1> 
<a href="/" title="{% blocktrans %}Back to '{{ race }}' homepage{% endblocktrans %}">{{ race 
}}</a> 
</h1> 
<p> 


{% for stage in tour_stages %} 
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{% cycle start end %}: {{ stage }}{% if forloop.counter|divisibleby:2 %}<br />{% else %}, 
{% endif %} 
{% endfor %} 
</p> 


{% trans %} 标签 还 支持 使 用 context 关键 字 指 定语 境 标记 : 


{% trans "May" context "month name" %} 


18.4.2 blocktrans 模板 标签 




















blocktrans 标签 用 于 标记 复杂 的 句子 ， 包 含 字面 量 和 变量 : 














{% blocktrans %}This string will have {{ value }} inside.{% endblocktrans %} 


























表达 式 ， 如 对 象 的 属性 或 模板 过 滤器 ， 要 绑 定 到 变量 上 ， 然 后 在 blocktrans 块 中 使 用 那个 变量 。 例 如 : 











{% blocktrans with amount=article.price %} 
That will cost $ {{ amount }}. 
{% endblocktrans %} 


{% blocktrans with myvar=value|filter %} 
This will have {{ myvar }} inside. 
{% endblocktrans %} 


一 个 blocktrans 标签 中 可 以 使 用 多 个 表达 式 : 


{% blocktrans with book t=book|title author_ t=author|title %} 
This is {{ book t }} by {{ author_t }} 
{% endblocktrans %} 


这 个 示例 也 可 以 写成 : 


{% blocktrans with book|title as book_t and author|title as author 七 %} 

















在 blocktrans 标签 中 不 能 使 用 其 他 块 级 标签 (如 {% for 时 或 {% if %}) 。 





























如 果 无 法 解析 传人 的 参数 ，blocktrans 使 用 deactivate_all() 函数 临时 停 用 当前 语言 ， 回 落 到 默认 语言 。 
这 个 标签 也 支持 复数 变形 。 使 用 方法 如 下 : 



































。 使 用 count 指定 并 绑 定 一 个 数值 。 这 个 数值 用 于 选择 正确 的 单 复数 形式 。 
。 在 {% blocktrans %} 和 {% endblocktrans %} 之 间 以 {% plural %} 标签 分 隔 单数 形式 和 复数 形式 。 


























举 个 例子 : 


{% blocktrans count counter=list|length %} 
There is only one {{ name }} object. 

{% plural %} 

There are {{ counter }} {{ name }} objects. 
{% endblocktrans %} 


一 个 更 复杂 的 例子 : 


{% blocktrans with amount=article.price count years=i.length %} 
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That will cost $ {{ amount }} per year. 

{% plural %} 

That will cost $ {{ amount }} per {{ years }} years. 
{% endblocktrans %} 












































如 果 在 使 ] 计 数值 的 同时 要 做 单 复数 变形 ， 还 要 把 值 绑 定 到 局 部 变量 上 ，bLocktrans 结构 在 背后 会 转换 成 
ungettext 调用 。 这 意味 着 ， 在 ungettext 中 使 用 变量 的 规则 在 这 里 也 适用 。 


在 blocktrans 块 中 无 法 反 向 查找 URL， 因 此 应 该 事先 查找 好 〈 并 存储 起 来 ) : 





























{% url 'path.to.view' arg arg2 as the_url %} 
{% blocktrans %} 

This is a URL: {{ the_url }} 

{% endbLocktrans %} 


{% blocktrans %} 还 支持 通过 context 关键 字 指 定语 境 


{% blocktrans with name=user .username context "greeting" %} 
Hi {{ name }} 
{% endblocktrans %} 








{% blocktrans %} 还 支持 trimmed 选项 ， 把 标签 内 容 首 尾 的 换行 符 去 掉 ， 把 每 一 行 首 尾 的 多 个 空白 蔡 换 成 一 
个 空格 ， 把 各 行 合并 成 一 行 。 


这 样 在 {% blocktrans 9 标签 中 就 可 以 缩 进 内 容 ， 而 不 必 担 心 缩 进 字符 会 出 现在 PO 文件 中 ， 免 得 妨碍 翻 


译 。 


























例如 ， 对 下 述 {% blocktrans 季 标签 来 说 : 


{% blocktrans trimmed %} 
First sentence. 
Second paragraph. 

{% endblocktrans %} 


在 得 到 的 PO 文件 中 是 "First sentence. Second paragraph."， 而 不 是 未 指定 trimmed 选项 时 的 "\n First 
sentence.\n Second sentence.\n"。 


18.4.3 传 给 标签 和 过 滤器 的 字符 串 字面 量 
可 以 使 用 熟悉 的 _() 句法 翻译 作为 参数 传 给 标签 和 过 滤器 的 字符 串 字 面 量 : 


{% some_tag _("Page not found") valuel|lyesno:_("yes,no") %} 


这 样 ， 标 签 和 过 滤器 得 到 的 都 是 翻译 后 的 字符 串 ， 无 需 关 心 如 何 翻译 。 


























这 里 ， 传 给 翻译 框架 的 是 字符 串 "yes ,no"， 而 不 是 单独 的 "yes" 和 "no" 。 翻 译 后 的 字符 串 要 保留 逗号 ， 这 样 
过 滤器 解析 代码 才 知道 如 何 把 参数 拆 开 。 例如 ， 德语 翻译 人 员 可 以 把 字符 串 ， yes,no" 翻译 成 "ja,nein"”( 保 


留 去 号 ) 。 























18.4.4 模板 中 给 翻译 人 员 看 的 注释 
与 在 Python 代码 中 一 样 ， 给 翻译 人 员 看 的 说 明 使 用 注释 编写 。 既 可 以 使 用 comment 标签 : 









































{% comment %}Translators: View verb{% endcomment %} 
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{% trans "View" %} 


{% comment %}Translators: Short intro blurb{% endcomment %} 
<p>{% blocktrans %} 

A multiline translatable literal. 

{% endblocktrans %} 
</p> 


也 可 以 使 用 一 行 形式 的 注释 结构 供 … 机: 























{# Translators: Label of a button that triggers search #} 
<button type="submit">{% trans "Go" %}</button> 


{# Translators: This is a text of the base template #} 
{% blocktrans %}Ambiguous translatable block of text{% endbLocktrans %} 


下 面 是 前 例 得 到 的 .po 文件 中 的 相应 片段 : 


#. TransLators: View verb 
# path/to/template/file.html:10 
msgid "View" 


msgstr 


#. Translators: Short intro blurb 
# path/to/template/file.html:13 
msgid "" 

"A multiline translatable" 
"literal." 


msgstr 


#. Translators: Label of a button that triggers search 
# path/to/template/file.html:100 
msgid "Go" 


msgstr 


#. Translators: This is a text of the base template 
# path/to/template/file.html:103 
msgid "Ambiguous translatable block of text" 


msgstr 


18.4.5 在 模板 中 切换 语言 


若 想 在 模板 中 选择 语言 ， 使 用 Language 模板 标签 : 
{% Load 118n %} 
{% get_current_Language as LANGUAGE CODE %} 
<!-- Current language: {{ LANGUAGE CODE }} --> 


<p>{% trans "Welcome to our page" %}</p> 


{% language 'en' %} 
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{% get_current_Language as LANGUAGE_CODE %} 
<!-- Current language: {{ LANGUAGE CODE }} --> 
<p>{% trans "Welcome to our page" %}</p> 


{% endlanguage %} 

















第 一 处 “Welcome to our page” 使 用 当前 语言 ， 但 是 第 二 处 始终 使 用 英语 。 





18.4.6 其 他 标签 
这 些 标签 也 需要 {% load il8n %}。 


。 {% get_available_languages as LANGUAGES 和 返回 一 个 元 组 列表 ， 元 组 的 第 一 个 元 素 是 语言 代码 ， 第 
二 个 元 素 是 语言 名 称 (翻译 成 当前 启用 的 语言 ) 。 

。 {% get_current_Language as LANGUAGE_CODE %} 返回 一 个 字符 串 ， 表 示 当 前 用 户 选择 的 语言 。 例 如 : 
en-us。 (参见 18.10.2 节 。) 

















。 {% get_current_language_bidi as LANGUAGE_BIDI %} 返回 当前 区 域 设置 的 书写 方向 。 为 True 时 ， 表 示 
由 右 向 左 书写 的 语言 ， 如 希 伯 来 语 和 阿拉 伯 语 ， 为 False 时 ， 表 示 由 左 向 右 书写 的 语言 ， 如 英语 、 法 


、 A A 众人 
语 、 德 语 ， 





























o 


启用 django.template.context_processors.ii8n 上 下 文 处 理 嚣 后， 每 个 RequestContext 对 象 都 能 访问 LAN- 
GUAGES、LANGUAGE_CODE 和 LANGUAGE_BIDI (相应 的 说 明 参 见 前 文 ) 。 


新 项 目 默认 未 启用 il8n 上 下 文 处 理 器 。 


使 用 相应 的 模板 标签 和 过 滤器 还 能 获取 任何 一 个 可 用 语言 的 信息 。 若 想 获得 某 个 语言 的 信息 ， 使 用 {% 
get_Language_info %} 标签 ; 




















{% get_Language_info for LANGUAGE_CODE as Lang %} 
{% get_Language_info for "pl" as Lang %} 


然后 可 以 访问 下 述 信息 : 


Language code: {{ lang.code }}<br /> 

Name of Language: {{ lang.name_local }}<br /> 
Name in English: {{ Lang.name }}<br /> 
Bi-directional: {{ lang.bidi }} 


此 外 ， 还 可 以 使 用 {% get_Language_info_List %} 标签 获得 一 组 语言 (例如 存储 在 LANGUAGES 中 的 可 用 语 
言 ) 的 信息 。 文 档 中 有 个 示例 ， 说 明 如 何 使 用 {% get_language_info_list %} 显示 一 个 语言 选择 菜单 。 




















除了 LANGUAGES 那 种 元 组 列表 之 外 ，{% get_Language_info_List %} 也 支持 由 语言 代码 构成 的 简单 列表 。 假 如 
视图 中 有 下 属 代码 : 





























context = {'available_languages': ['en', 'es', 'fr']} 


return render(request, 'mytemplate.html', context) 





就 可 以 在 模板 中 迭代 各 个 语言 : 





{% get_language_info_list for available_ languages as Langs %} 
{% for lang in langs %} ... {% endfor %} 











为 了 方便 ， 还 提供 了 相应 的 过 滤器 : 
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。 {{ LANGUAGE_CODE|Language_name }} (German) 
。 {{ LANGUAGE_CODE|language_name_local }} (Deutsch) 


。 {{ LANGUAGE_CODE|language_bidi }} (False) 


18.5 国际 化 JavaScript 代码 
为 JavaScript 添加 翻译 面临 诸多 问题 : 


。 JavaScript 代码 无 法 访问 gettext。 
。 JavaScript 代码 无 法 访问 .po 或 .mo 文件 ， 它们 要 由 服务 器 分 发 。 
。 JavaScript 的 翻译 目录 要 尽量 保持 小 身材 。 


























为 了 解决 这 些 问 题 ，Django 提供 了 一 种 集成 方案 : 把 翻译 传人 JavaScript， 因 此 可 以 在 JavaScript 代码 中 访问 
gettext 等 。 


18.5.1 javascript_catalog 视图 


这 些 问题 的 主要 解决 方案 是 django.views.ti1l8n.javascript_cataLog() 视图 ， 它 发 送 一 个 JavaScript 代码 库 ， 
里 面包 含 模 拟 gettext 接口 的 函数 和 翻译 字符 串 数 组 。 








这 些 翻译 字符 串 来 自 应 用 程序 或 Django 核心 ， 具 体内 容 取决 于 在 info_dict 或 URL 中 作 何 指定 。L0- 
CALE_PATHS 设置 列 出 的 路 径 也 包含 在 内 。 











这 个 视图 的 用 法 如 下 : 











from django.views.i18n import javascript_catalog 


js_info dict = { 
'packages': ('your.app.package',), 
} 


urlpatterns = [ 
url(r'^jsi1i8n/$', javascript_catalog, js_info_dict), 


] 





packages 中 的 各 个 字符 串 应 该 是 点 分 Python 路 径 (与 INSTALLED_APPS 中 的 字符 串 格式 一 样 ) ， 指 向 包含 Lo- 
cale 目录 的 包 。 如 果 指 定 多 个 包 ， 各 个 包 中 的 翻译 目录 会 合并 成 一 个 。 这 样 ， 在 JavaScript 中 就 可 以 使 用 不 
同 应 用 中 的 翻译 字符 串 。 





























翻译 字符 串 的 使 用 顺序 是 ，packages 参数 中 靠 后 的 包 比 靠 前 的 包 优先 级 高 。 遇 到 翻译 冲突 时 要 知道 这 一 点 。 








这 个 视图 默认 使 用 gettext 的 djangojs 域 ， 不 过 可 以 使 用 domaiin 参数 修改 。 
可 以 把 包 名 放 入 URL 模式 ， 让 这 个 视图 动态 加 载 翻 译 : 


urlpatterns = [ 
url(r'^jsi1i8n/(?P<packages>\S+?)/$', javascript_catalog), 
] 


























此 时 ， 可 以 在 URL 中 指定 包 名 列表 (以 加 号 分 隔 ) 。 如 果 一 个 页 面 使 用 不 同 应 用 中 的 代码 ， 而 且 所 用 的 应 用 
经 常 变动 ， 就 可 以 这 么 做 ， 因 为 你 并 不 想 加 载 一 个 大 的 目录 文件 。 出 于 安全 考虑 ， 在 URL 中 指定 的 值 要 么 是 
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django.conf， 要 么 是 INSTALLED_APPS 设置 中 的 某 个 包 。 


在 LOCALE_PATHS 设置 所 列 路 径 里 找到 的 JavaScript 翻译 始终 包含 在 内 。 为 了 让 翻译 查找 顺序 算法 与 Python 和 
模板 保持 一 致 ，LOCALE_PATHS 设置 中 列 出 的 目录 ， 靠 前 的 优先 级 比 靠 后 的 高 。 














18.5.2 使 用 JavaScript 翻译 目录 


若 想 使 用 翻译 目录 ， 像 下 面 这 样 动态 生成 script 标签 ; 





<script type="text/javascript" src="{% url 'django.views.i1i8n.javascript catalog' %}"></script> 


这 行 代码 通过 反 向 URL 查找 机 制 找 出 JavaScript 目录 视图 的 URL。 加 载 目录 后 ，JavaScript 代码 可 以 使 用 标 
准 的 gettext 接口 访问 翻译 目录 : 








document.write(gettext('this is to be translated')); 
ngettext 接口 也 可 用 : 


var object_cnt = 1 // 或 0、2、3， 
s = ngettext('literal for the singular case', 
'literal for the plural case', object cnt); 





其 至 还 有 字符 串 插 值 函数 : 





function interpolate(fmt, obj, named); 





1 





重 值 句法 借鉴 自 Python， 因 此 interpolate 水 数 既 支持 基于 位 置 插 值 ， 也 支持 基于 名 称 插值 。 




















。 基于 位 置 插值 ，obj 是 一 个 JavaScript 数组 对 象 ， 里 面 的 元 素 依 序 内 插 到 fmt 中 的 占 位 符 所 在 的 位 置 。 
例如 : 








fmts = ngettext('There is %s object. Remaining: %s', 
'There are %s objects. Remaining: %s', 11); 

s = interpolate(fmts, [11, 20]); 

// s 的 值 是 'There are 11 objects. Remaining: 20' 


。 基于 名 称 插值 ， 把 named 参数 设 为 true 时 选择 这 个 模式 。obj 是 一 个 JavaScript 对 象 或 关联 数组 。 例 





如 : 
di 三 . 直 
count: 10， 
total: 50 
由 


fmts = ngettext('Total: %(totaL)s，there is %(count)s object ' ， 
"there are %(count)s of a total of %(totaL)s objects', d.count); 
s = interpolate(fmts, d, true); 


不 过 ， 别 过 量 使 用 ， 这 上 毕竟 是 JavaScript 代码 ， 要 不 断 通过 正则 表达 式 代 换 。 这 种 模拟 的 方式 没有 Python 字 
符 串 插值 的 速度 快 ， 因 此 应 该 留 给 真正 需要 的 情形 (例如 结合 ngettext， 输 出 正确 的 复数 形式 ) 。 






























































18.5.3 注意 性 能 











每 次 请 求 javascript_catalog() 视图 ， 它 都 从 .mo 文件 中 生成 翻译 目录 。 因 为 输出 是 不 变 的 (至 少 对 网 站 的 
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特定 版 本 来 说 是 如 此 ) ， 所 以 或 许可 以 缓存 。 





服务 器 端 缓存 能 降低 CPU 负载 ， 通 过 cache_page() 装饰 器 可 以 轻易 实现 。 为 了 在 翻译 有 变化 时 让 缓存 失 
效 ， 可 以 提供 一 个 与 版 本 有 关 的 键 前 级 (如 下 例 所 示 ) ， 或 者 把 这 个 视图 映射 到 带 版 本 号 的 URL 上 。 











from django.views.decorators.cache import cache_page 
from django.views.i1i8n import javascript_catalog 


# 翻译 有 变化 时 ，get_version() 返回 的 值 必须 变化 

Qcache_page(86400, key_prefix='js1i8n-%s' % get_version()) 

def cached _ javascript_catalog(request, domain='djangojs', packages=None): 
return javascript_catalog(request, domain, packages) 





客户 端 缓存 能 节省 带宽 ， 让 网 站 加 载 的 速度 变 得 更 快 。 如 果 使 用 ETag (USE_ETAGS = True) ,客户 端 缓存 就 
已 经 启用 了 。 和 否则 ， 可 以 使 用 条 件 请 求 装 饰 器 。 在 下 述 示例 中 ， 重 启 应 用 服务 器 后 缓存 便 失 效 。 




















from django.utils import timezone 
from django.views.decorators.http import last modified 
from django.views.i1i8n import javascript_catalog 


last_modified date = timezone.now() 
Qlast modified(Lambda req, **kw: last_modified _ date) 


def cached _ javascript_catalog(request, domain='djangojs', packages=None): 
return javascript_catalog(request, domain, packages) 





甚至 还 可 以 在 部 署 过 程 中 事先 生成 JavaScript 翻译 目录 ， 然 后 作为 静态 文件 伺服 。 





18.6 国际 化 URL 模式 





Django 为 国际 化 URL 模式 提供 了 两 种 机 制 ; 














。 在 URL 模式 前 面 添 加 语言 前 级 ， 让 LocaleMiddleware 从 所 请 求 的 URL 中 检测 要 使 用 的 语言 。 
。 通过 django.utils.translation.ugettext_lazy() 函数 把 URL 模式 本 身 标记 为 可 以 翻译 的 。 











这 两 种 机 制 都 要 求 为 每 个 请 求 设 定语 言 ， 也 就 是 说 ，MIDDLEWARE_CLASSES 设置 中 要 列 出 django.middle- 
ware. locale.LocaleMiddleware, 


18.6.1 在 URL 模式 中 添加 语言 前 组 








可 以 在 根 URL 配置 中 使 用 这 个 函数 ， 此 时 Django 会 自动 把 当前 语言 代码 添加 到 ii8n_patterns() 定义 的 所 
有 URL 模式 前 面 。 例 如 : 














from django.conf.urls import include, url 

from django.conf.urls.ii8n import ii8n_patterns 
from about import views as about views 

from news import views as News_views 

from sitemap.views import sitemap 


urlpatterns = [ 
url(r'^sitemap\.xml$', sitemap, name='sitemap_xml'), 
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news_patterns = [ 
url(r'^$', news_views.index, name='index'), 
url(r'^category/(?P<slug>[\w-]+)/$', 
News_views .category, 
Name="' category' )， 
url(r'^(?P<slug>[\w-]+)/$', news_views.details, name='detail'), 


urlpatterns += ii8n_patterns( 
url(r'^about/$', about_views.main, name='about'), 
url(r'^news/', include(news_patterns, namespace='news')), 


) 


这 样 定义 URL 模式 后 ，Django 会 自动 在 i18n_patterns 函数 添加 的 URL 模式 前 面 加 上 语言 前 级 。 例 如 : 








>>> from django.core.urlresolvers import reverse 
>>> from django.utils.translation import activate 
>>> activate('en') 

>>> reverse('sitemap_xml') 

'/sitemap.xml' 

>>> reverse('news:index') 

' /en/news/' 


>>> activate('nl') 
>>> reverse('news:detail', kwargs={'slug': 'news-slug'}) 
'/nl/news/news-slug/' 

















i18n_patterns() 只 允许 在 根 URL 配置 中 使 用 。 如 果 在 引入 的 URL 配置 中 使 用 ， 会 抛 出 ImproperlyConfig- 


ured 异常 。 














18.6.2 翻译 URL 模式 


URL 模式 可 以 使 用 ugettext_lazy() 函数 标记 为 可 翻译 的 。 例 如 : 


from django.conf.urls import include, url 
from django.conf.urls.ii8n import ii8n_patterns 
from django.utils.translation import ugettext lazy as _ 


from about import views as about views 
from news import views as News_views 
from sitemaps.views import sitemap 


urlpatterns = [ 
url(r'^sitemap\.xml$', sitemap, name='sitemap_xml'), 


news_patterns = [ 
url(r'^$', news_views.index, name='index'), 
url(_(r'^category/(?P<slug>[\w- ]+)/$'), 
News_views.category, 
name='category' ) ， 
url(r'^(?P<slug>[\w-]+)/$', news_views.details, name='detail'), 
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urlpatterns += i1i8n_patterns( 
url(_(r'^about/$'), about views.main, name='about'), 
url(_(r'^news/'), include(news_patterns, namespace='news')), 


) 

















了 翻译 之 后 ，reverse() 函数 会 返回 当前 语言 的 URL。 例如: 


>>> from django.core.urlresolvers import reverse 
>>> from django.utils.translation import activate 


>>> activate('en ') 
>>> reverse('news:category', kwargs={'slug': 'recent'}) 
'/en/news/category/recent/' 


>>> activate('nl') 
>>> reverse('news:category', kwargs={'slug': 'recent'}) 
'/nl/nieuws/categorie/recent/' 














多 数 情况 下 ， 最 好 只 在 已 经 深 加 语言 代码 前 级 的 模式 块 (使 用 i18n_patterns()) 中 使 用 翻译 的 URL， 以 防 
翻译 的 URL 不 小 心 与 未 翻译 的 URL 模式 冲突 。 


18.6.3 在 模板 中 反 向 解析 


在 模板 中 ， 反 向 解析 得 到 的 本 地 化 URL 始终 使 用 当前 语言 。 若 想 链接 到 另 一 个 语言 ， 使 用 Language 模板 标 
签 。 这 个 标签 在 所 包含 的 块 中 启用 指定 的 语言 。 


























{% Load ii8n %} 
{% get_available_languages as languages %} 


{% trans "View this category in:" %} 

{% for lang_code, lang_name in Languages %} 
{% language lang_code %} 
<a href="{% url 'category' slug=category.slug %}">{{ Lang_name }}</a> 
{% endlanguage %} 

{% endfor %} 


Language 标签 只 有 一 个 参数 ， 即 语言 代码 。 


18.7 创建 本 地 语言 文件 














把 应 用 程序 中 的 字符 串 字面 量 标记 为 可 翻译 的 之 后 ， 还 要 翻译 。 下 面 说 明 具 体 做 法 。 


























18.7.1 消息 文件 


首先 ， 要 为 新 语言 创建 消息 文件 。 这 是 一 种 纯 文 本 文件 ， 针 对 一 门 语言 ， 包 含 所 有 可 翻译 的 字符 串 ， 以 及 目 
标语 言 的 表述 。 消 息 文件 的 扩展 名 为 .po。 

















Django 自 带 的 django-admin makemessages 命令 用 于 自动 创建 和 维护 消息 文件 。 

















280 -第 18 章 国际 化 


makemessages 命令 (以 及 后 文 要 讨论 的 compilemessages 命令 ) 使 用 GNU gettext 工具 集中 的 几 个 命令 : 


xgettext、msgfmt、msgmerge 和 msguniq。 
Django 支持 的 gettext 最 低 版 本 为 0.15。 
创建 或 更 新 消息 文件 使 用 下 述 命令 : 
django-admin makemessages -L de 
其 中 ，de 是 消息 文件 的 语言 名 称 。 例 如 ， 巴 西 葡萄 牙 语 是 pt_BR， 奥 地 利 德语 是 de_AT， 印 尼 语 是 id。 


这 个 脚本 应 该 在 下 述 两 个 位 置 运行 : 





。 Django 项 目的 根 目 录 (manage.py 文件 所 在 的 目录 ) 。 
。 某 个 Django 应 用 的 根 目录 。 





这 个 脚本 扫描 项 目 或 应 用 的 源码 树 ， 找 出 所 有 标记 为 可 翻译 的 字符 串 (参见 18.10.3 节 ， 还 要 确保 正确 配置 了 
LOCALE_PATHS) ， 然 后 在 locale/LANG/LC_MESSAGES 目录 中 创建 (或 更 新 ) 消息 文件 。 对 de 语言 来 说 ， 创 建 
的 文件 是 LocaLe/de/LC_MESSAGES/django.po。 























在 项 目的 根 目录 中 运行 makemessages 命令 时 ， 提 取出 来 的 字符 串 会 自动 分 配 到 正确 的 消息 文件 中 。 即 ， 如 果 
应 用 中 有 tocale 目录 ， 从 那个 应 用 的 文件 中 提取 出 来 的 字符 串 保存 到 locale 目录 中 ; 否则， 提取 的 字符 串 
保存 到 LOCALE_PATHS 设置 中 的 第 一 个 目录 里 ， 如 果 LOCALE_PATHS 为 空 ， 报 错 。 








django-admin makemessages 命令 会 扫描 每 个 扩展 名 为 .htmL 和 .txt 的 文件 。 若 想 覆 盖 默 认 值 ， 使 用 - -exten- 
sion 或 -e 选项 指定 文件 扩展 名 : 





django-admin makemessages -L de -e txt 
多 个 扩展 名 使 用 逗号 分 开 ， 也 可 以 多 次 使 用 --extension 或 -e 选项 : 


django-admin makemessages -L de -e html,txt -e xml 


为 JavaScript 源码 创建 消息 文件 时 ， 要 使 用 特殊 的 域 “djangojs”"， 而 非 -e js。 











如 果 没 有 安装 gettext 实用 工具 ，makemessages 创建 的 是 空 文件 。 遇 到 这 种 情况 ， 要 么 安装 gettext 实用 工 
具 ， 要 么 复制 英语 消息 文件 (如果 有 的 话 ，locale/en/LC_MESSAGES/django.po) ， 在 此 基础 上 翻译 。 

















在 Windows 中 ， 若 想 使 用 makemessages 命令 ， 要 安装 GNU gettext 实用 工具 ， 详 情 参 见 18.7.4 节 。 











.po 文件 的 格式 很 简单 。 每 个 .po 文件 中 都 有 少量 的 元 数据 ， 例 如 翻译 维护 人 员 的 联系 信息 ， 余 下 的 大 部 分 
则 是 消息 列表 ， 即 一 对 对 翻译 语言 和 针对 目标 语言 的 翻译 。 


假如 Django 应 用 中 有 下 面 这 个 翻译 字符 串 ， 








_("Welcome to my site.") 
django-admin makemessages 命令 创建 的 .po 文件 中 会 包含 下 述 片段 ， 即 一 个 消息 


#: path/to/python/module.py:23 
msgid "Welcome to my site." 
msgstr "" 
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信 
下 


可 





和 说明 一 下 : 








。 msgid 是 源码 中 的 翻译 字符 串 。 不 要 修改 。 














。 msgstr 是 针对 目标 语言 的 翻译 。 一 开始 是 空 的 ， 























。 为 了 便于 参考 ， 在 每 个 消息 中 ，msgitd 那 行 上 面 者 


文件 名 和 行 号 。 


较 长 的 消息 有 些 特 殊 。 此 时 ， 紧 跟 在 msgstr (或 msgid) 后 面 的 是 一 个 空 字符 
而 且 一 行 一 个 字符 串 。 这 些 字符 串 直 接 拼接 在 一 起 。 别 忘 了 在 每 个 字符 串 末 尾 添 加 空格 ， 否 则 两 行内 容 就 连 











在 一 起 了 。 
考虑 到 gettext 工具 的 内 部 运作 方式 ， 以 及 要 在 Django 






































有 一 行 注释 (以 # 玫 


1 你 负责 翻译 。 记 住 ， 翻 译 要 放 在 引号 里 。 
F 头 ) ， 指 明 翻 译 字 符 串 所 在 的 

















的 核心 和 应 用 程序 中 使 用 非 ASCII 字符 串 ，PO 文件 








和 ， 内 容 在 接 下 来 的 几 行 中 ， 





的 编码 必须 使 用 UTF-8 (创建 PO 文件 时 默认 使 用 这 个 编码 ) 。 这 样 每 个 人 使 用 的 编码 都 相同 ， 便 于 Django 











处 理 PO 文件。 











若 想 重新 扫描 源码 和 模板 ， 找 出 新 的 翻译 字符 串 ， 更 新 所 有 语言 的 所 有 消息 文件 ， 运 行 下 述 命令 : 























django-admin makemessages -a 


18.7.2 编译 消息 文件 





创建 消息 文件 ， 以 及 每 次 修改 消息 文件 之 后 ， 要 使 用 gettext 把 它 编译 成 更 高 效 的 格式 。 这 一 步 通 过 django- 


admin compilemessages 命令 操作 。 



































这 个 命令 把 所 有 .po 文件 编译 成 .mo 文件 ， 这 是 一 种 二 进 制 文件 ， 针 对 gettext 做 了 优化 。 在 运行 django- 
运行 下 述 命令 : 





admin makemessages 命令 的 那个 目录 中 运 和 


django-admin compilemessages 











就 这 样 。 现 在 翻译 可 供 使 用 了 。 











在 Windows 中 ， 知 想 使 用 django-admin compilemessages 命令 ， 要 安装 GNU gettext 实用 工 


18.7.4 节 。 





























具 ， 详 情 参 见 


Django 只 支持 UTF-8 编码 的 .po 文件 ， 而 且 不 能 有 BOM (Byte Order Mark， 字 节 序 标记 ) ， 因 此 如 果 你 的 






































文本 编辑 器 默认 在 文件 开头 添加 BOM， 要 重新 配置 编 $ 








18.7.3 为 JavaScript 源码 创建 消息 文件 





由 器 
二 o 











对 JavaScript 代码 来 说 ， 创 建 和 更 新 消息 文件 的 方式 与 Django 中 的 其 他 消息 文件 一 样 ， 使 用 django-admin 
makemessages 命令 。 唯 一 的 区 别 是 ， 要 明确 把 域 设 为 djangojs， 即 提供 -d djangojs 参数 ， 如 下 所 示 : 























django-admin makemessages -d djangojs -L de 





这 个 命令 创建 或 更 新 德语 的 JavaScript 消息 文件 。 更 新 消息 文件 之 后 ， 像 其 他 Django 消息 文件 一 样 ， 运 行 











django-admin compilemessages 命令。 


18.7.4 在 Windows 中 安装 gettext 


只 有 想 提 取消 息 ID 或 编译 消息 文件 (.po) 的 人 才 需 要 安装 gettext。 翻 译本 身 只 需要 编辑 现 有 的 消息 文 


























件 ， 但 是 如 果 你 自己 想 创建 消息 文件 ， 或 者 想 测试 或 

















译 有 改动 的 消息 文 伯 


EF， 就 要 安装 gettext 实用 工 











上 


|vo 
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。 从 GNOME 服务 器 中 下 载 以 下 两 个 ZIP 文件 : 


° gettext-runtime-X.zip 
° gettext-tools-X.zip 
(其 中 Xx 是 版 本 号 ， 必 须 使 用 0.15 或 以 上 版 本 。) 




















。 把 两 个 ZIP 文件 中 的 bin\ 目录 里 的 内 容 提 取出 来 ， 放 到 系统 中 的 同一 个 文件 夹 里 (例如 C:\Program 
Files\gettext-utils) 。 


。 更 新 系统 路 径 : 





。 依次 打开 “控制 面板 > 系统 > 高 级 > 环境 变量 ” 
。 在 “系统 变量 "列表 中 点 击 Path， 再 点 击 “ 编 辑 ”。 


。 在 “变量 值 ” 字 段 后 面 添加 ;C:\Program Files\gettext-utils\bin。 























也 可 以 使 用 从 别处 获取 的 gettext 二 进 制 文件 ， 只 要 能 正确 运行 xgettext --version 就 行 。 如 果 在 Windows 
命令 提示 符 中 运行 xgettext --version 命令 后 弹出 一 个 对 话 框 ， 提 示 xgettext.exe 出 错 ，Windows 将 把 它 关 
闭 ， 此 时 千 万 别 使 用 与 gettext 包 有 关 的 Django 翻译 工具 。 








18.7.5 自 定义 makemessages 命令 








el 
HH 





如 果 想 把 额外 参数 传 给 xgettext， 要 自 定义 makemessages 命令 ,覆盖 xgettext_options 属性 


from django.core.management .Commands import makemessages 


class Command(makemessages.Command ) : 
xgettext_options = makemessages.Command.xgettext_options + ['--keyword=mytrans'] 


如 果 想 更 灵活 一 些 ， 还 可 以 为 自 定 义 的 makemessages 命令 增加 一 个 参数 : 


from django.core.management.commands import makemessages 
class Command(makemessages.Command): 


def add_arguments(self, parser): 
super(Command, self).add arguments(parser) 
parser .add argument('--extra-keyword', 
dest= 'xgettext_keywords ' ， 
action='append') 


def handle(self, *args, **options): 
xgettext_ keywords = options.pop('xgettext_ keywords') 
if xgettext_keywords: 
self.xgettext_options = ( 
makemessages.Command.xgettext_options[:] + 
['--keyword=%s' % kwd for kwd in xgettext_keywords] 
) 


super(Command, self).handle(*args, **options) 
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18.8 显 式 设 定 当 前 语言 











你 可 能 想 显 式 为 当前 会 话 设 定 语言 ， 比 如 说 用 户 的 语言 偏好 设置 从 其 他 系统 中 获取 时 。 前 面 已 经 介绍 过 
django.utils.translation.activate()。 这 个 函数 只 影响 当前 线程 。 如 果 想 在 整个 会 话 中 都 使 用 所 设 的 语 
言 ， 还 要 修改 会 话 中 的 LANGUAGE_SESSION_KEY : 









































from django.utils import translation 

User_Language = 'fr' 

translation.activate(user_language) 
request.session[translation.LANGUAGE_SESSION_KEY] = user_language 























通常 ， 这 二 者 结合 在 一 起 使 用 : 先 使 用 django.utils.translation.activate() 为 当前 线程 设 定语 言 ， 然 后 修 
改 会 话 ， 让 后 续 请 求 继 续 使 用 。 


如 果 不 使 用 会 话 ， 设 定 的 语言 保存 在 一 个 cookie 中 ， 其 名 称 由 LANGUAGE_COOKIE_NAME 配置 。 例 如 : 









































from django.utils import translation 

from django import http 

from django.conf import settings 

User_Language = 'fr' 

translation.activate(user_language) 

response = http.HttpResponse(...) 
response.set_cookie(settings.LANGUAGE_ COOKIE_ NAME, user_language) 


18.9 在 视图 和 模板 之 外 使 用 翻译 


Django 为 视图 和 模板 提供 了 丰富 的 国际 化 工具 ， 但 是 并 没有 限制 只 能 用 于 Django 代码 。Django 的 翻译 机 制 
能 把 任何 文本 翻译 成 Django 支持 的 语言 (当然 ， 相 应 的 翻译 目录 要 存在 ) 。 


你 可 以 加 载 一 个 翻译 目录 ， 激 活 它 ， 把 文本 翻译 成 你 选择 的 语言 ， 但 是 别 忘 了 切换 回 原 语言 ， 因 为 翻译 目录 
在 线程 中 激活 ， 会 影响 同一 个 线程 中 运行 的 所 有 代码 。 


例如 : 


























from django.utils import translation 
def welcome_translated(languyage): 
cur_language = translation.get_language() 
Cr 
translation.activate(language) 
text = translation.ugettext('welcome') 
finally: 
translation.activate(cur_language) 
return text 


此 时 ， 不管 LANGUAGE_CODE 设置 和 中 间 件 设 定 的 语言 是 什么 ， 如 果 指 定语 言 为 de”"， 得 到 的 是 “Willkom- 


3? 


men ”。 








这 里 涉及 的 几 个 函数 是 ，django.utils.translation.get_language()， 返 回 当前 线程 中 使 用 的 语言 ，djan- 
go.utils.translation.activate()， 在 当前 线程 中 激活 指定 的 翻译 目录 ;django.utils.transla- 
tion.check_for_language()， 检查 Django 是 否 支 持 指定 的 语言 。 
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18.10 实现 方式 说 明 


18.10.1 Django 翻译 机 制 的 特殊 之 处 




















Django 的 翻译 机 制 采用 Python 标准 库 中 的 gettext 模块 。 如 果 你 了 解 gettext， 将 会 发 现 Django 处 理 翻 译 的 
方式 有 些 特别 之 处 : 









































。 字符 串 域 是 django 或 djangojs。 域 用 于 区 分 不 同 程序 在 同一 个 位 置 (通常 是 /usr/share/locale/) 存 
储 的 消息 文件 。django 域 针 对 Python 和 模板 代码 的 翻译 字符 串 ， 加 载 到 全 局 翻译 目录 中 。djangojs 域 
只 针对 JavaScript 翻译 目录 ， 目 的 是 让 JavaScript 翻译 目录 尽量 保持 小 体积 。 

。 Django 不 单独 使 用 xgettext， 而 是 使 用 Python 对 xgettext 和 msgfmt 的 包装 程序 。 这 样 做 基本 上 是 为 
了 操作 方便 。 































































































18.10.2 Django 如 何 发 现 语言 偏好 设置 




















准备 好 翻译 之 后 ， 或 者 直接 使 用 Django 自 带 的 翻译 时 ， 要 激活 翻译 。 
在 这 背后 ，Django 采用 一 种 十 分 灵活 的 方式 判断 该 使 用 哪个 语言 一 一 全 局 或 针对 各 个 用 户 ， 抑 或 二 者 兼 具 。 

















若 想 全 局 设 定语 言 偏 好 设置 ， 使 用 LANGUAGE_CODE 设置 。Django 把 这 个 设置 设 定 的 语言 作为 默认 语言 ， 即 本 
中 


地 化 中 间 件 找 不 到 匹配 的 翻译 时 所 做 的 补救 措施 (参见 下 文 ) 。 


如 果 只 想 让 Django 使 用 你 的 母语 ， 只 需 设 定 LANGUAGE_CODE 设置 ， 并 确保 相应 的 消息 文件 及 编译 后 的 版 本 


Cs 


(.mo) 存在 。 


如 果 想 让 用 户 自行 选择 语言 ， 还 要 使 用 LocaleMiddleware。LocaleMiddleware 根据 请 求 中 的 数据 选择 语言 ， 
然后 为 用 户 定制 内 容 。 


若 想 使 用 LocaleMiddleware， 把 'django.middleware.locale.LocaleMiddleware' 添加 到 MIDDLEWARE_CLASSES 
设置 中 。 中 间 件 是 有 一 定 顺序 的 ， 请 遵循 下 述 指导 方针 : 

























































































。 确保 是 头 几 个 中 间 件 之 一 。 
。 应 该 放 在 SessionMiddleware 后 面 ， 因 为 LocaleMiddleware 要 使 用 会 话 数 据 。 而 且 要 放 在 CommonMid- 
dleware 前 面 ， 因 为 CommonMiddleware 要 知道 激活 了 哪个 语言 才能 解析 所 请 求 的 URL。 


。 如 果 使 用 CacheMiddleware， 把 LocaleMiddleware 放 在 它 后 面 。 
































例如 ，MIDDLEWARE_CLASSES 设置 可 能 是 这 样 的 : 


MIDDLEWARE CLASSES = [ 
'django.contrib.sessions.middleware.SessionMiddleware', 
'django.middleware.locale.LocaleMiddleware', 
'django.middleware.common.CommonMiddleware', 


] 
中 间 件 的 更 多 说 明 参 见 第 17 章 。 








LocaleMiddleware 通过 下 述 法 则 确定 用 户 的 语言 偏好 设置 : 








。 首先 ， 查 看 所 请 求 URL 的 语言 前 缀 。 仪 当 URL 配置 中 使 用 了 it18n_patterns 函数 才 会 这 么 做 。 关 于 
语言 前 级 ， 以 及 如 何 国际 化 URL 模式 ， 参 见 18.6 市 。 


。 如 果 无 法 确定 ， 查 看 当前 用 户 会 话 中 的 LANGUAGE_SESSION_KEY 键 。 
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。 如 果 无 法 确定 ， 查 看 一 个 cookie。 这 个 cookie 的 名 称 由 LANGUAGE_COOKIE_NAME 设置 设 定 。 (默认 名 称 
为 django_Language。 ) 

。 如 果 无 法 确定 ， 查 看 Accept-Language 首部 。 这 个 首部 由 浏览 器 发 送 ， 作 用 是 告诉 服务 器 可 接受 的 语 

言 ( 按 优先 级 顺序 列 出 ) 。Django 依次 尝试 这 个 首部 中 的 语言 ， 直 到 找 出 可 用 的 翻译 。 

无 法 确定 ， 使 用 全 局 的 LANGUAGE_CODE 设置 。 
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在 每 一 步 中 ， 语 言 偏 好 设置 的 值 都 应 该 是 字符 串 形 式 的 标准 语言 格式 。 例 如 ， 巴 西 葡萄 牙 语 是 'pt- 
br ' 。 

。 如 果 基 语言 可 用 ， 而 子 语言 不 可 用 ，Django 将 使 用 基 语 言 。 例 如 ， 如 果 用 户 指定 的 语言 是 de-at ( 奥 
地 利 德 语 ) ， 而 应 用 程序 只 提供 了 de 的 翻译 ，Django 将 使 用 de。 

。 只 能 选择 LANGUAGES 设置 中 列 出 的 语言 。 如 果 想 把 选择 限制 在 几 种 语言 之 间 (因为 应 用 程序 没有 提供 
所 有 语言 ) ， 把 LANGUAGES 设 为 一 个 语言 列表 。 例 如 : 






















































































LANGUAGES = [ 
('de', _('German')), 
('en', _('English')), 
] 














这 样 就 限制 只 能 在 德语 和 英语 (及 其 子 语言 ， 如 de-ch 或 en-us) 之 间 选 择 。 


。 如 果 像 前 一 点 所 说 ， 定 义 了 LANGUAGES 设置 ， 可 以 把 语言 名 称 标记 为 翻译 字符 串 ， 不 过 要 使 用 uget- 
text_Lazy()， 而 不 能 使 用 ugettext() ， 以 免 循 环 导 入 。 下 面 举 个 例子 : 


























from django.utils.translation import Ugettext_Lazy as _ 


LANGUAGES = [ 
('de', _('German')), 
('en', _('English')), 
] 

















LocaleMiddleware 确定 用 户 的 语言 偏好 设置 之 后 ， 将 其 存 人 每 个 HttpRequest 对 象 的 request.LANGUAGE_CODE 
属性 中 。 这 样 ， 在 视图 代码 中 就 可 以 读 取 了 。 下 面 举 个 例子 : 















































from django.http import HttpResponse 


def hello world(request, count): 
if request.LANGUAGE CODE == 'de-at': 
return HttpResponse("You prefer to read Austrian German.") 
else: 
return HttpResponse("You prefer to read another language.") 





注意 ， 静 态 翻 译 (不 经 中 间 件 ) 的 语言 在 settings.LANGUAGE_CODE 中 ， 而 动态 翻译 ( 
request.LANQUAGE_CODE 中 。 


攻 


过 中 间 件 ) 的 语言 在 














18.10.3 Django 如 何 发 现 翻译 











运行 时 ，Django 把 字面 量 翻译 合并 到 一 起 ， 构 建 一 个 统一 的 翻译 目录 ， 存 储 在 内 存 中 。 为 此 ，Django 遵循 下 
述 规则 ， 确 定 以 何 种 顺序 扫描 不 同 的 文件 路 径 ， 加 载 编 译 好 的 翻译 文件 ( .mo) ， 以 及 以 何 种 顺序 加 载 相 同 字 
面 量 的 多 个 翻译 : 
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。 LOCALE_PATHS 设置 中 列 出 的 目录 优先 级 最 高 ， 而 且 排 在 前 面 的 目录 优先 级 比 排 在 后 面 的 目录 高 。 


。 然后 ， 查 看 INSTALLED_APPS 设置 中 列 出 的 各 个 应 用 ， 使 用 各 个 应 用 Locale 目录 中 的 翻译 。 这 个 设置 中 
排 在 前 面 的 应 用 比 排 在 后 面 的 优先 级 高 。 


。 最 后 ，Django 在 django/conf/tLocale 目录 中 提供 了 一 些 基础 翻译 ， 做 为 一 种 后 备 机 制 。 



































































































































包含 翻译 的 目录 应 该 以 区 域名 称 命 名 ， 例 如 de、pt_BR、es_AR， 等 等 。 


























这 样 ， 你 便 可 以 编写 自 带 翻译 的 应 用 程序 ， 而 且 可 以 在 项 目 中 覆盖 基础 翻译 。 此 外 ， 也 可 以 构建 一 个 由 多 个 
应 用 构成 的 大 型 项 目 ， 把 所 有 翻译 都 放 在 一 个 通用 的 消息 文件 中 。 选 择 权 在 你 手中 。 


消息 文件 目录 的 结构 类 似 : 
















































































。 在 LOCALE_PATHS 设置 列 出 的 各 个 路 径 中 搜索 <language>/LC_MESSAGES/django. (po|mo)。 
。 SAPPPATH/LocaLe/<Language>/LC_MESSAGES/django.(po|mo)。 


。 SPYTHONPATH/django/conf/LocaLe/<Language>/LC_MESSAGES/django.(po|mo)。 

















消息 文件 使 用 django-admin makemessages 命令 创建 。gettext 使 用 的 二 进 制 .mo 文件 使 用 django-admin com- 
pilemessages 命令 生成 。 




















运行 django-admin compilemessages 命令 时 还 可 以 让 编译 器 处 理 LOCALE_PATHS 设置 中 列 出 的 所 有 目录 。 








18.11 接 下 来 


下 一 章 讨论 Django 中 的 安全 措施 。 
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专业 的 Web 应 用 程序 开发 者 的 一 项 重要 职责 是 确保 网 站 的 安全 性 。 


如 今 ，Django 框架 已 经 十 分 成 熟 ， 大 多 数 常 见 的 安全 问题 都 由 框架 本 身 以 某 种 方式 解决 了 ， 然 而 ， 安 全 措施 
难保 万 全 ， 因 为 随时 都 有 新 的 威胁 出 现 ， 所 以 ， 作 为 Web 开发 者 的 我 们 要 以 身 作 则 ， 确 保 网 站 和 Web 应 用 
的 安全 性 。 


Web 安全 性 是 个 涉及 面 很 广 的 话题 ， 很 难 在 一 章 的 内 容 中 深入 探讨 。 本 章 简 述 Django 提供 的 安全 特性 ， 
给 出 一 些 安全 方面 的 建议 ， 确 保 Django 驱动 的 网 站 在 99% 的 情况 下 是 安全 的 ，Web 安全 的 最 新 情况 则 有 人 
自己 去 跟踪 。 
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如 果 想 详细 了 解 Web 安全 ， 可 以 看 看 Django 的 安全 问题 存档 ， 以 及 维基 百科 中 的 “Web application security” 
词 条 。 








19.1 Django 内 置 的 安全 特性 


19.1.1 跨 站 脚本 防护 


跨 站 脚本 攻击 (Cross Site Scripting，XSS) 的 原理 是 一 个 用 户 在 另 一 个 用 户 的 浏览 器 中 注入 客户 端 脚 本 。 














恶意 脚本 通常 存储 在 数据 库 中 ， 当 用 户 查 看 页 面 或 点 击 链接 时 再 读 取出 来 ， 在 用 户 的 浏览 器 中 执行 。 然 而 ， 
只 要 没有 对 页 面 中 的 数据 做 好 净化 ， 任 何不 可 信 的 数据 源 ， 如 cookie 或 Web 服务 ， 都 有 可 能 成 为 XSS 攻击 
的 源头 。 


使 用 Django 模板 能 防护 大 多 数 XSS 攻击 。 然 而 ， 一 定 要 了 解 它 提供 的 保护 措施 ， 以 及 不 足 之 处 。 




































































Django 模板 会 过 滤 字 符 ， 尤 其 是 对 HTML 而 言 危险 的 字符 。 这 能 防止 用 户 输 入 多 数 恶意 内 容 ， 但 却 不 是 万 
无 一 失 的 。 例 如 ， 无 法 防止 输入 下 述 内 容 : 














<style class={{ var }}>...</style> 


如 果 var 的 值 是 'class1l onmouseover=javascript:func()'， 那 么 这 有 段 输入 就 可 能 导致 执行 非法 的 JavaScript 
代码 (取决 于 浏览 器 如 何 泻 染 不 完美 的 HTML) 。 (把 属性 的 值 放 在 引号 中 能 解决 这 个 问题 。) 









































此 外 ， 自 定义 的 模板 标签 、safe 标签 、mark_safe 和 禁用 autoescape 时 一 定 要 慎重 使 用 is_safe。 









































如 果 使 用 模板 系统 输出 HTML 之 外 的 格式 ， 要 注意 ， 此 时 需要 转 义 的 字符 和 单词 可 能 完全 不 同 。 


























在 数据 库 中 存储 HTML 时 也 要 十 分 小 心 ， 尤 其 是 要 取出 并 显示 HTML 时 。 














19.1.2 跨 站 请 求 伪 造 防护 





























跨 站 请 求 伪造 (Cross Site Request Forgery，CSRF) 攻击 的 原理 是 在 用 户 不 知情 或 未 准许 的 情况 下 以 用 户 的 身 
份 执行 操作 。 


Django 内 置 的 措施 能 防护 多 种 CSRF 攻击 ， 前 提 是 你 要 适时 启用 。 然 而 ， 与 任何 缓和 技术 一 样 ， 这 些 措施 也 
不 足 之 处 。 
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例如 ，CSRF 模块 可 以 全 局 或 在 具体 的 视图 上 禁用 。 如 果 想 禁用 ,一定 要 心中 有 数 。 如 果 网 站 的 某 些 二 级 域 
名 不 在 你 的 控制 之 内 ， 还 有 其 他 局 限 。 


























CSRF 防护 的 原理 是 ， 检 查 每 个 P0ST 请 求 中 的 一 次 性 令 牌 。 这 样 能 确保 恶意 用 户 无 法 重 放 提 交 的 表单 ， 因 此 
也 就 无 法 在 用 户 不 知情 的 情况 下 提交 表单 。 除 非 用 户 获 知 了 一 次 性 令 牌 ， 而 那 是 每 个 用 户 专用 的 〈 存 储 在 


cookie 中 ) 。 
















































































使 用 HTTPS 时 ，CsrfViewMiddleware 会 检查 HTTP Referer 首部 中 的 URL 是 否 来 自 相 同 的 源 (包括 二 级 域名 
和 端口 ) 。HTTPS 增强 了 安全 性 ， 因 此 只 要 可 能 就 应 该 使 用 HTTPS， 而 且 要 把 不 安全 的 连接 转发 到 安全 的 
连接 ， 并 为 支持 的 浏览 器 启用 HSTS 。 


























除非 真 的 有 必要 ， 不 要 轻易 使 用 csrf_exempt 装饰 需 装 饰 视 


-A 

















Django 的 CSRF 中 间 件 和 模板 标签 为 防护 跨 站 请 求 伪 造 提 供 了 易于 使 用 的 措施 。 











CSRF 攻击 的 第 一 道 防线 是 确保 GET 请 求 ( 以 及 其 他 “安全 的 ”请 求 方法 ， 参 见 HTTP 1.1 规范 RFC 2616 中 的 
“9.1.1 Safe Methods”) 没有 副作用 。“ 不 安全 的 ”请 求 方法 ， 如 PoST、PUT 和 DELETE 可 以 参照 下 述 步 又 保护 。 



































用 法 
在 视图 中 防护 CSRF 的 步 又 如 下 : 














1. MIDDLEWARE_CLASSES 设置 默认 已 激活 CSRF 中 间 件 。 如 果 覆 盖 了 那个 设置 ， 记 得 要 把 'django.middle- 
ware.csrf.CsrfViewMiddleware' 放 在 所 有 假定 已 经 处 理 过 CSRF 攻击 的 视图 中 间 件 前 面 。 如 果 禁 用 了 
这 个 中 间 件 (不 推荐 ) ， 可 以 在 想 保 护 的 视图 上 使 用 csrf_protect() 装饰 器 (参见 下 文 ) 。 


2， 在 通过 PosT 方法 发 送 的 表单 中 ， 如 果 表 单 的 目标 地 址 是 内 部 URL， 在 <form> 元 素 中 使 用 csrf_token 
标签 。 例 如 : 






















































































un 
































<form action="." method="post"> 
{% csrf_token %} 


























如 果 POST 表单 的 模板 地 址 是 外 部 URL， 不 能 这 么 做 ， 否 则 ，CSRF 令 牌 就 泄露 了 ， 导 致 网 站 存在 漏 

洞 。 

3. 确保 在 对 应 的 视图 函数 中 使 用 'django.tempLate.context_processors.csrf' 上 下 文 处 理 器 。 通 常 , 方 
法 有 如 下 两 种 : 



































a， 使 用 RequestContext， 它 始终 使 用 'django.template.context_processors.csrf' (不 管 在 TEM- 
PLATES 设置 中 配置 的 是 哪个 模板 上 下 文 处 理 器 ) 。 如 果 使 用 的 是 泛 视 图 或 扩展 应 用 ， 无 需 自己 
动手 ， 因 为 它们 使 用 的 全 是 RequestContext。 


b.， 自己 动手 导入 上 下 文 处 理 器 ， 使 用 它 生 成 CSRF 令 牌 ， 再 将 其 添加 到 模板 上 下 文中 。 例 如 





















































from django.shortcuts import render_to_response 
from django.template.context_processors import csrf 


def my_view(request): 
c= 十 
c.update(csrf(request)) 
# ..， 其 他 视图 代码 


return render_to_response("a_template.html", c) 


你 也 可 以 自己 编写 render_to_response()， 实 现 这 一 步 。 
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Ajax 


虽然 上 述 方法 可 以 在 Ajax POST 请 求 中 使 用 ， 但 是 有 些 不 便 : 每 个 POST 请 求 都 不 能 忘 了 在 POST 数据 中 发 
送 CSRF 令 牌 。 鉴 于 此 ，Django 提供 了 另外 一 种 方法 : 为 XMLHttpRequest 设 定 自 定义 的 X-CSRFToken 首部 ， 
将 其 值 设 为 CSREF 令 牌 。 通 常 ， 这 样 更 简单 ， 因 为 很 多 JavaScript 框架 都 提供 了 钩子 ， 能 轻易 为 每 个 请 求 设 
定 首部 。 


为 此 ， 首 先 要 获取 CSRF 令 牌 。 建 议 从 csrftoken cookie 中 获取 。 按 上 述 步 又 为 视图 启用 CSRF 防护 后 ， 会 


设 定 这 个 cookie。 











存储 CSRF 令 牌 的 cookie 默认 名 为 csrftoken， 不 过 也 可 以 使 用 CSRF_COOKIE_NAME 设置 自 定义 。 
获取 令 牌 的 方法 很 简单 : 





// 使 用 jQuery 
function getCookie(name) { 
var cookieValuye = null; 
if (document.cookie && document.cookie != ''){ 
var cookies = document.cookie.split(';'); 
for (var i = 0; i < cookies.Length; i++) { 
var cookie = jQuery.trim(cookies[i]); 
// cookie 的 名 称 以 指定 字符 串 开 头 吗 ? 


if (cookie.substring(0, name.length + 1) == (name + '=')) { 
cookieValuye = decodeURIComponent(cookie.substring(name.length + 1)); 
break; 

} 


} 


return cookieValue; 


} 


var csrftoken = getCookie('csrftoken'); 
上 述 代码 可 以 通过 jQuery Cookie 插件 简化 ， 无 需 定义 getCookie 函数 : 


var csrftoken = $.cookie('csrftoken'); 


DOM 中 也 有 CSRF 令 牌 ,但 是 仅 当 在 模板 中 使 用 csrf_token 时 才 有 。cookie 中 存储 的 令 牌 才 
是 正 源 ，CsrfViewMiddleware 首选 cookie 中 的 令 牌 ， 而 非 DOM 中 的 。 不 管 这 么 多 ， 只 要 
DOM 中 有 令 牌 ，cookie 中 就 有 ， 所 以 应 该 使 用 cookie 中 的 令 牌 。 


如 果 视 图 泻 染 的 模板 中 没有 csrf_token 标签 ，Django 可 能 不 会 设 定 CSRF 今 牌 cookie。 动 态 
添加 到 页 面 中 的 表单 往往 是 这 种 情况 。 为 了 解决 这 个 问题 ，Django 提供 了 一 个 视图 装饰 器 ， 强 


制 设 定 那 个 cookie: ensure_csrf_cookie()。 


最 后 ， 在 Ajax 请 求 中 设 定 X-CSRFToken 首部 。 为 了 防止 把 CSRF 令 牌 发 给 其 他 域名 ， 在 jQuery 1.5.1 及 以 上 
版 本 中 应 该 使 用 settings.crossDomain。 








function csrfSafeMethod(method) { 
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// 这 些 HTTP 方法 不 需要 CSRF 防护 
return (/^(GET|HEAD|OPTIONS|TRACE)S$/.test(method)); 
} 
$.ajaxSetup({ 
beforeSend: function(xhr, settings) { 
if (!csrfSafeMethod(settings.type) && !this.crossDomain) { 
xhr .setRequestHeader("X-CSRFToken", csrftoken); 
} 
} 
}); 


其 他 模板 引擎 


如 果 使 用 的 模板 引擎 不 是 Django 内 置 的 ， 可 以 自己 动手 在 表单 中 设 定 CSRF 令 牌 。 当 然 ， 首 先 要 保证 模板 上 
下 文中 有 令 牌 。 


例如 ， 使 用 Jinja2 模板 语言 时 ， 可 以 这 样 编写 表单 : 











<div style="display:none"> 
<input type="hidden" name="csrfmiddlewaretoken" value="{{ csrf_token }}"> 
</div> 


也 可 以 像 上 述 Ajax 代码 那样 使 用 JavaScript 获取 CSRF 令 牌 的 值 。 
装饰 器 方法 


如 果 不 想 使 用 csrfviewMiddleware 提供 的 全 面 防护 措施 ， 可 以 在 需要 保护 的 视图 上 使 用 csrf_protect 装饰 
器 ， 其 作用 与 CsrfViewMiddleware 完全 一 样 。 输 出 中 有 CSRF 令 牌 的 视图 ， 以 及 接受 PosT 表单 数据 的 视图 
(二 者 通常 是 同一 个 视图 ， 但 也 有 例外 ) 都 要 使 用 这 个 装饰 器 。 


不 建议 只 使 用 这 个 装饰 器 ， 因 为 一 旦 忘记 就 暴露 了 安全 漏洞 。 以 防 万 一 ， 可 以 二 者 同时 使 用 ， 
由 此 增加 的 消耗 很 少 。 








用 法 : 


from django.views.decorators.csrf import csrf_protect 
from django.shortcuts import render 


@csrf_protect 
def my_view(request): 
c= {} 
i 
return render(request, "a_template.html", c) 





如 果 使 用 基于 类 的 视图 ， 请 参阅 Django 文档 。 





请 求 被 拒 


默认 情况 下 ， 如 果 入 站 请 求 未 通过 CsrfviewMiddleware 的 检查 ， 将 返回 “403 Forbidden”* 响 应 。 出 现 这 种 情 
况 ， 通 常 说 明 真 的 遭 到 跨 站 请 求 伪 造 攻击 了 ， 或 者 是 程序 设计 有 问题 ，POST 表单 中 没有 CSRF 令 牌 。 
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然而 ， 错 误 页 面 不 是 十 分 友好 ， 因 此 你 可 能 想 自 己 编写 视图 处 理 这 种 情况 。 为 此 ， 只 需 设 定 CSRF_FAIL- 
URE_VIEW 设置 。 





原理 


CSRF 防护 的 背后 是 这 样 的 : 











。 CSRF cookie 是 一 个 随机 值 (与 会 话 无 关 的 一 次 性 值 ) ， 其 他 网 站 无 法 访问 。 这 个 cookie 由 Csr- 
fviewMiddleware 设 定 。 这 个 cookie 的 作用 是 永久 的 ， 但 是 因为 无 法 设 定 永 不 过 期 的 cookie， 所 以 每 个 
响应 都 会 调用 django.middleware.csrf.get_token() (内 部 使 用 这 个 函数 获取 CSRF 今 牌 ) ， 随 响应 一 

。 每 个 外 送 的 POST 表单 都 有 一 个 名 为 “csrfmiddlewaretoken” 的 隐藏 字段 。 这 个 字段 的 值 就 是 CSRF cook- 
ie 中 的 值 。 这 个 字段 由 一 个 模板 标签 添加 。 

。 入 站 请 求 ， 只 要 使 用 的 不 是 HTTP GET、HEAD、OPTIONS 或 TRACE， 必须 有 CSRF cookie， 而 且 必 须 有 值 

正确 的 “csrfmiddlewaretoken” 字 段 。 否 则 ， 用 户 会 得 到 403 错误 。 这 项 检查 由 CsrfViewMiddleware 实 

施 。 


。 此 外 ，CsrfviewMiddleware 会 对 HTTPS 请 求 做 严格 的 来 源 检查 。 这 是 为 了 避免 在 HITPS 中 使 用 与 会 
话 无 关 的 一 次 性 值 时 导致 的 中 间 人 攻击 ， 因 为 通过 HTTPS 与 网 站 通信 的 客户 端 接受 HTTP Set-Cookie 
首部 〈 真 遗憾 ) 。 (HTTP 请 求 不 做 来 源 检查 ， 因 为 在 HTTP 中 Referer 首部 不 太 可 靠 。) 这 样 能 确 
保 只 有 源 自 自己 网 站 的 表单 才能 把 数据 发 送 回 来 。 

。 故意 忽略 GET 请 求 (以 及 RFC 2616 定义 的 其 他 “安全 ”请 求 ) 。 这 些 请 求 决 不 能 带 有 潜在 有 害 的 副 作 
用 ， 因 此 即便 遭受 CSRF 攻击 ，GET 请 求 也 没什么 危害 。RFC 2616 把 PoST、PUT 和 DELETE 定义 为 “不 
安全 的 ”请 求 方法 ， 除 此 之 外 的 其 他 所 有 方法 都 假定 是 安全 的 ;不 安全 的 方法 要 尽力 防护 。 






















































































































































































缓存 





如 果 在 模板 中 使 用 了 csrf_token 标签 (或 者 以 其 他 方式 调用 了 get_token 也 数 ) ，CsrfViewMiddleware 会 添 
加 一 个 cookie， 并 为 响应 添加 Vary: Cookie 首部 。 这 意味 着 ， 如 果 使 用 得 当 (UpdateCacheMiddleware 放 在 其 
他 所 有 中 间 件 前 面 ) ，CsrfviewMiddleware 能 与 缓存 中 间 件 协同 工作 。 

























































































然而 ， 如 果 在 具体 的 视图 上 使 用 缓存 装饰 器 ， 那 么 CSRF 中 间 件 就 来 不 及 设 定 Vary 首部 或 CSRF cookie， 从 
而 缓存 的 响应 中 二 者 都 没有 。 






































对 需要 插入 CSRF 仿 牌 的 视图 来 说 ， 应 该 先 使 用 django.views.decorators.csrf.csrf_protect() 装饰 器 ; 

















from django.views.decorators.cache import cache_page 
from django.views.decorators.csrf import csrf_protect 





he_page(60 * 15) 


def my_view(request): 











如 果 使 用 基于 类 的 视图 ， 请 参阅 Django 文档 。 


测试 

















CsrfViewMiddleware 往往 会 给 测试 视图 函数 带 来 麻烦 ， 因 为 每 个 PoST 请 求 都 要 带 有 CSRF 令 牌 。 鉴 于 此 ， 
Django 的 HTTP 测试 客户 端 做 了 特殊 处 理 ， 设 定 了 一 个 旗 标 ， 让 这 个 中 间 件 和 csrf_protect 装饰 器 放松 警 
惕 ， 不 再 拒绝 请 求 。 除 此 之 外 ，HTTP 测试 客户 端的 行为 都 与 前 文 所 述 的 一 样 〈 例 如， 会 发 送 CSRF cook- 


ie) 。 
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如 果 某 些 情况 下 想 让 测试 客户 端 检查 CSRF， 可 以 创建 一 个 测试 客户 端 实例 ， 要 求 它 检查 CSRF: 


>>> from django.test import Client 
>>> csrf_client = Client(enforce_csrf_checks=True) 


不 足 之 处 











网 站 的 二 级 域名 能 在 客户 端 为 整个 域名 设 定 cookie。 有 了 cookie 和 其 中 的 令 牌 ， 二 级 域名 就 能 绕 过 CSRF 防 
线 。 唯 一 能 避免 这 个 问题 的 措施 是 ， 确 保 二 级 域名 在 受信 任 的 人 手中 (或 者 至 少 不 能 设 定 cookie) 。 


注意 ， 即 便 不 考虑 CSRF， 也 不 能 把 二 级 域名 交 给 不 可 信 的 一 方 ， 因 为 还 有 其 他 漏洞 (如 会 话 固定 ) 在 现今 
的 浏览 器 中 无 法 轻易 补 上 。 


























边缘 情况 


某 些 视图 有 不 同 寻常 的 需求 ， 因 此 不 能 使 用 这 里 所 述 的 常规 方式 处 理 。 遇 到 非常 规 情况 时 ， 可 以 使 用 几 个 实 
用 工具 。 这 些 工具 的 使 用 场景 在 下 一 节 中 说 明 。 














19.1.3 CSRF 实用 工具 























下 述 各 示例 假定 你 使 用 的 是 基于 函数 的 视 





路 
































。 如 果 使 用 基于 类 的 视图 ， 请 参阅 Django 文档 。 
django.views.decorators.csrf.csrf_exempt(view) 


多 数 视图 需要 CSRF 防护 ， 但 少数 不 需要 。 不 要 禁用 CSRF 中 间 件 ， 然 后 在 需要 防护 的 视图 上 使 用 csrf_pro- 
tect 装饰 器 ;正确 的 做 法 是 启用 CSRF 中 间 件 ， 使 用 csrf_exempt() 装饰 器 。 


这 个 装饰 器 指明 视图 免 受 CSRF 中 间 件 的 保护 。 例 如 : 
















































































from django.views.decorators.csrf import csrf_exempt 
from django.http import HttpResponse 


@csrf_exempt 
def my_view(request): 


return HttpResponse('Hello world') 


django.views.decorators.csrf.requires_csrf_token(view) 























些 情 况 下 ，CsrfviewMiddleware.process_view 可 能 不 在 视图 之 前 运行 (例如 404 和 500 处 理 程序 ) ， 但 是 
仍 想 在 表单 中 使 用 CSRF 令 牌 。 









































通常 ， 如 果 CsrfViewMiddleware.process_view 或 等 效 的 函数 (如 csrf_protect) 没有 运行 ，csrf_token 模板 
标签 将 不 起 作用 。 视 图 装饰 器 requires_csrf_token 可 以 确保 这 个 标签 一 定 起 作用 。 这 个 装饰 器 的 原理 与 
csrf_protect 类 似 ， 但 是 从 不 拒绝 和 人 站 请 求 。 


例如 : 









































from django.views.decorators.csrf import requires_csrf_token 
from django.shortcuts import render 


@requires_csrf_token 
def my_view(request): 


c= 
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着 
return render(request, "a_template.html", c) 

















还 有 些 视图 不 受 保护 ， 被 csrf_exempt 饮 免 了 ,但 是 仍 需 引 入 CSRF 令 牌 。 此 时 ， 在 csrf_exempt() 后 面 使 用 
requires_csrf_token() ( 即 requires_csrf_token 放 在 最 内 层 ) 。 


























最 后 ， 有 些 视图 仅 在 满足 特定 条 件 时 需要 CSRF 防护 ， 而 其 他 情况 下 则 不 需要 。 这 种 需求 的 一 种 解决 方法 
是 ， 在 整个 视图 函数 上 使 用 csrf_exempt()， 然 后 在 需要 CSRF 防护 的 代码 路 径 上 使 用 csrf_protect()。 


例如 : 
































from django.views.decorators.csrf import csrf_exempt, csrf_protect 


@csrf_exempt 


def my_view(request): 


@csrf_protect 
def protected path(request): 
do_something() 


if some_condition(): 

return protected_path(request) 
else: 

do_something_else() 


django.views.decorators.csrf.ensure_csrf_cookie(view) 

















这 个 装饰 器 强制 视图 发 送 CSRF cookie。 比 如 说 ， 如 果 通 过 Ajax 发 起 POST 请 求 的 页 面 中 没有 包含 csrf_to- 
ken 的 HTML 表单 ， 此 时 就 需要 发 送 CSRF cookie。 这 种 需求 的 解决 方法 是 在 视图 上 使 用 ensure_csrf_cook- 
ie() 装饰 需 。 



































扩展 应 用 和 可 复 用 的 应 用 


因为 开发 者 能 够 禁用 CsrfVviewMiddLeware， 所 以 扩展 应 用 中 的 全 部 相关 视图 都 使 用 csrf_protect 装饰 器 确保 
应 用 能 防护 CSRF 攻击 。 其 他 可 复 用 的 应 用 开发 者 ， 如 果 想 得 到 这 种 保障 ， 建 议 也 在 视图 上 使 用 csrf_pro- 
tect 装饰 髓 。 



































CSRF 设置 


Django 的 CSRF 防护 行为 受 几 个 设置 的 控制 ; 








。 CSRF_COOKIE _ AGE 

。 CSRF_COOKIE_ DOMAIN 

。 CSRF_COOKIE_HTTPONLY 
。 CSRF_COOKIE_NAME 

。 CSRF_COOKIE_PATH 

。 CSRF_COOKIE_SECURE 


。 CSRF_FAILURE_VIEW 


各 个 设置 的 详细 说 明 参 见 附录 D。 
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19.1.4 SQL 注入 防护 


SQL 注入 (injection) 是 一 种 攻击 类 型 ， 原 理 是 恶意 用 户 在 数据 库 9 





致 记录 被 删 ， 或 者 导致 数据 泄露 。 


使 用 Django 的 查询 集合 ， 底 
查询 或 执行 自 定义 的 SQL。 使 用 这 两 个 功能 时 要 谨慎 一 些 ， 应 该 始终 转 义 由 用 户 控 和 























extra() 时 要 格外 小 心 。 


19.1.5 点 击 劫持 防护 


点 击 劫持 (clickjacking) 是 一 利 


在 隐蔽 的 





医 架 上 



































执行 任意 的 SQL 代码 。SQL 注入 可 能 


慨 的 数据 库 驱 动 会 正确 转 义 得 到 的 SQL。 然 而 ，Django 也 允许 开发 者 编写 原始 
判 的 参数 。 此 外 ， 使 用 














Ph， 骗取 用 户 的 任性 ， 让 他 们 点 击 ， 这 就 是 点 击 支持 。 


攻击 类 型 ， 原 理 是 在 框架 (frame) 中 内 艇 恶意 网 站 。 攻 击 者 把 恶意 网 站 内 藤 














Django 通过 XFrame0ptionsMiddLeware 防护 点 击 劫持， 在 支持 X-Frame-0ptions 首部 的 浏览 器 中 ， 无 法 把 网 站 
内 秘 在 框架 中 。 这 项 防护 措施 可 以 在 具体 的 视图 上 禁用 ， 还 可 以 配置 发 送 的 首部 值 。 


如 果 网 站 无 需 通 过 框架 内 区 到 第 三 方 网 站 中 ,或 者 只 允许 网 站 的 一 小 部 分 内 藤 到 第 三 方 网 站 中 ， 





























用 这 个 中 间 件 。 


点 击 劫持 示例 


假设 有 个 在 线 商 店 ， 在 一 个 页 面 上 已 登录 的 用 户 可 以 点 击 "Buy Now”， 购 买 商品 。 为 了 方便 操作 ， 用 户 选择 
FP 创建 一 个 “I Like Ponies” 按 钮 ， 然 后 在 透明 的 框架 中 加 载 在 线 商店 











记 住 登录 状态 。 
的 页 面 ， 把 不 可 见 的 “Buy Now” 按 钮 羡 放 到 “I Like Ponies 按钮 上 。 用 户 访问 攻击 者 的 网 站 ， 点 
Ponies”*"”， 此 时 便 会 意外 点 击 “Buy Now” 按 钮 ， 在 不 知情 的 情况 下 购买 了 商品 。 














避免 点 击 动 持 
























































攻击 者 可 以 在 自己 的 网 站 











强烈 建议 


ail 















































FT Like 





现代 的 浏览 器 会 遵照 HTTP Xx-Frame-0ptions 首部 的 设 定 ， 判 断 是 否 允 许 在 框架 中 加 载 资源 。 如 果 响 应 中 的 这 
个 首部 值 为 SAMEORIGIN， 那 么 浏览 器 只 允许 来 自 同一 网 站 的 请 求 在 框架 中 加 载 资源 。 如 果 首 部 的 值 为 DENY， 


浏览 器 将 禁止 在 











E 架 中 加 载 资源 ， 不 管 请 求 来 自 哪个 网 站 都 不 允许 。 















































为 了 在 响应 中 添加 这 个 首部 ，Django 提供 了 两 种 简单 的 方式 : 











， 一 个 简单 的 9 




















FP 间 件 ， 为 所 有 响应 设 定 这 个 首部 。 











。 一 系列 视图 装饰 器 ， 用 于 覆盖 中 间 件 的 设置 ， 或 者 只 在 特定 的 视图 上 设 定 这 个 首部 。 


用 法 


为 所 有 响应 设 定 X-Frame-0ptions 


若 想 为 网 站 中 的 所 有 啊 应 设 定 X-Frame-0ptions 首部 ， 在 MIDDLEWARE_CLASSES 设置 











ware.CLickjacking.XFrameOptionsMiddteware ' : 


MIDDLEWARE_CLASSES = [ 
和 
'django.middleware.clickjacking.XFrameOptionsMiddleware', 
ss 


] 


startproject 命 今 4 











成 的 设置 文件 默认 启用 了 这 个 中 间 件 。 


PP 添加 'django.middle- 
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默认 情况 下 ， 这 个 中 间 件 把 每 个 出 站 响应 的 X-Frame-0ptions 首部 设 为 SAMEORIGIN。 如 果 想 设 为 DENY， 像 这 
样 设 定 X_FRAME_0PTIONS 设置 . 





X_FRAME_OPTIONS = 'DENY' 





启用 这 个 中 间 件 后 ， 可 能 有 些 视图 不 需要 设 定 X-Frame-0ptions 首部 。 此 时 ， 可 以 使 用 一 个 视图 装饰 器 告知 
中 间 件 ， 别 在 视图 上 设 定 X-Frame-0ptions 首部 : 








from django.http import HttpResponse 
from django.views.decorators.clickjacking import xframe_options_exempt 


@xframe_options_exempt 
def ok_ to load in a frame(request): 
return HttpResponse("This page is safe to load in a frame on any site.") 


在 具体 的 视图 上 设 定 X-Frame-0ptions 
为 了 便于 在 具体 的 视图 上 设 定 X-Frame-0ptions 首部 ，Django 提供 了 下 述 几 个 装饰 器 : 


from django.http import HttpResponse 
from django.views.decorators.clickjacking import xframe_options_deny 
from django.views.decorators.clickjacking import xframe_options_sameorigin 


def view_ one(request): 
return HttpResponse("I won't display in any frame!") 


def view_ two(request): 
return HttpResponse("Display in a frame if it's from the same 
origin as me.") 











注意 ， 这 些 装 饰 器 可 以 与 XFrame0ptionsMtddLeware 结合 起 来 使 用 ， 通 过 装饰 器 覆盖 中 间 件 的 全 局 行为 。 








不 足 之 处 














只 有 在 现代 的 浏览 器 中 x-Frame-Options 首部 才能 防护 点 击 支持 。 旧 浏览 器 直接 忽略 这 个 首部 ， 需 要 使 用 其 
他 方式 防护 点 击 动 持 。 











支持 X-Frame-0ptions 的 浏览 


。 JInternet Explorer 8+ 
。 Firefox 3.0.9+ 

。 Opera 10.5+ 

。 Safari 4+ 


。 _ Chrome 4.1+ 


19.1.6 SSL/HTTPS 














把 网 站 部 署 在 HTTPS 后 面 对 安 全 性 肯定 更 好 ， 但 并 不 适用 所 有 情况 。 如 果 不 使 用 HITPS， 恶 意 用 户 可 以 咱 
探 身 份 认 证 凭据 等 在 客户 端 和 服务 器 之 间 传 输 的 信息 ， 有 时 攻击 者 甚至 可 以 自 改 发 给 二 者 的 数据 。 
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如 果 想 使 用 HTTPS 提供 的 保护 措施 ， 而 且 在 服务 器 上 已 经 启用 HTTPS， 可 能 还 需要 做 以 下 几 件 事 : 





。 如 有 必要 ， 设 定 SECURE_PROXY_SSL_HEADER， 确 保全 面 理解 涉及 的 提醒 。 如 果 不 设 定 这 个 设置 ， 可 能 暴 
漏 CSRF 漏洞 ， 未 正确 设置 也 有 一 定 的 危险 。 

把 HITP 请 求 重 定向 到 HTTPS。 这 一 步 可 以 通过 一 个 自 定义 中 间 件 实现 。 注 意 ，SE- 
CURE_PROXY_SSL_HEADER 有 个 坑 。 如 果 使 用 反 向 代理 ， 让 主 Web 服务 器 重 定向 更 容易 ， 也 更 安全 。 

使 用 “安全 的 ”cookie。 如 果 浏 览 器 一 开始 是 通过 HTTP 连接 的 (多 数 浏 览 器 默认 如 此 ) ， 现 有 的 cookie 
可 能 齐 到 港 赴 。 鉴 于 此 ， 应 该 把 SESSION_COOKIE_SECURE 和 CSRF_COOKIE_SECURE 设置 设 为 True。 这 人 么 
做 的 目的 是 让 浏览 器 只 通过 HTTPS 发 送 那 两 个 cookie。 注 意 ， 这 样 设 定之 后 ， 在 HTTP 连接 中 会 话 不 
可 用 ， 而 且 CSRF 防护 措施 拒绝 接受 通过 HTTP 发 送 的 PosT 数据 (如 果 把 HTTP 流量 重 定向 到 
HTTPS ， 那 就 没 问题 ) 。 

使 用 HTTP Strict Transport Security (HSTS) 。HSTS 是 一 个 HTTP 首部 ， 告 知 浏览 器 ， 针 对 指定 网 站 
的 后 续 请 求 都 使 用 HTTPS (参见 下 文 ) 。 我 们 已 经 把 HTTP 请 求 重 定向 到 HTTPS 了 ， 再 加 上 

HSTS ， 只 要 成 功 连接 了 一 次 ， 后 续 请 求 就 能 享用 SSL 增添 的 安全 措施 。HSTS 通常 在 Web 服务 器 上 
配置 。 













































































HTTP Strict Transport Security 


如 果 你 的 网 站 只 允许 通过 HTTPS 访问 ， 可 以 设 定 Strict-Transport-Security 首部 ， 告 诉 现代 的 浏览 器 ， 
(在 一 段 时 间 内 ) 拒绝 通过 不 安全 的 连接 访问 你 的 域名 。 这 样 能 降低 被 某 些 SSL 层面 的 中 间 人 攻击 的 风险 。 


如 果 把 SECURE_HSTS_SECONDS 设置 设 为 非 零 整 数值 ，SecurityMiddLeware 会 为 所 有 HTTPS 响应 设 定 这 个 首 
部 。 

启用 HSTS 时 ， 最 好 先 使 用 小 一 点 的 值 测试 ， 例 如 设 为 一 小 时 : SECURE_HSTS_SECONDS = 3600。 只 要 Web 浏 
览 器 发 现 有 HSTS 首部 ， 就 会 在 一 段 时 间 内 拒绝 通过 不 安全 的 连接 (HITP) 访问 你 的 域名 。 


确保 网 站 中 的 所 有 静态 资源 都 能 正确 伺服 之 后 〈( 即 HSTS 没有 造成 影响 ) ， 最 好 增加 时 长 (经 常设 为 
31536000 秒 ， 即 一 年 ) ， 让 不 常 访问 的 访客 也 得 到 保护 。 























此 外 ， 如 果 把 SECURE_HSTS_INCLUDE_SUBDOMAINS 设置 设 为 True，SecurityMiddleware 会 在 Strict-Transport- 
Security 首部 中 添加 includeSubDomains 标签 。 这 是 推荐 的 做 法 (所 有 二 级 域名 也 只 能 通过 HTTPS 访问 ) ， 
如 若 不 然 ， 通 过 不 安全 的 连接 访问 二 级 域名 还 是 可 能 存在 漏洞 。 


HSTS 策略 应 用 于 整个 域名 ， 而 不 只 是 设 定 Strict-Transport-Security 首部 的 那个 URL。 
此 ， 仅 当 整 个 域名 都 通过 HTTPS 伺服 时 才 应 该 使 用 HSTS。 严 格 遵 守 HSTS 首部 的 浏览 器 遇 到 
过 期 的 、 自 签名 的 或 无 效 的 SSL 证 书 时 拒绝 用 户 跳 过 提醒 ， 不 允许 继续 访问 。 使 用 HSTS 时 ， 
要 确保 证 书 始终 有 效 ! 


如 果 网 站 部 署 在 负载 均衡 程序 或 反 向 代理 服务 器 后 面 ， 而 啊 应 中 没有 Strict-Transport-Secu- 
rity 首部 ， 可 能 是 因为 Django 没 将 其 视 作 安全 的 连接 。 此 时 可 能 要 设 定 SE- 
CURE_PROXY_SSL_HEADER 设置 。 
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19.1.7 验证 Host 首部 











某 些 情况 下 ，Django 使 用 客户 端 提供 的 Host 首部 构建 URL。 昌 然 为 了 防止 跨 站 脚本 攻击 ， 这 个 首部 的 值 做 
了 净化 ， 但 是 在 跨 站 请 求 伪造 、 缓 存 中 毒 攻击 和 邮件 链接 中 毒 中 ，Host 首部 的 值 可 能 是 虚假 的 。 





















































尽管 Web 服务 器 的 配置 看 似 是 安 全 的 ， 但 是 依然 会 受到 虚假 Host 首部 的 影响 。 所 以 ，Django 会 验证 Host 首 
部 ， 调 用 django.http.HttpRequest.get_host() 方法 时 ， 检 查 得 到 的 值 是 否 在 ALLOWED_HOSTS 设置 中 。 























只 有 调用 get_host() 方法 时 才 会 执行 这 个 检查 。 如 果 直 接 从 request.META 中 读 取 Host 首部 ， 就 跳 过 了 这 项 





安全 保护 措施 。 





19.1.8 会 话 安全 性 


CSRF 防护 措施 的 不 足 之 处 是 ， 要 求 二 级 域名 不 在 不 可 信 的 用 户 手 中 。 类 似 地 ，django.contrib.sessions 也 


这 样 的 缺点 。 详 情 参 见 文档 中 对 会 话 安全 性 的 说 明 。 




















19.1.9 用 户 上 传 的 内 容 


。 如 果 你 的 网 站 允许 上 传 文件 ， 强 烈 建议 在 Web 服务 器 的 配置 中 把 上 传 文 
防 遭 到 拒绝 服务 (Denial of Service，DoS) 攻击 。 在 Apache 中 可 以 使 用 





件 的 大 小 限 


LimitRequestBod 











出 为 合理 的 值 ， 以 


y 指令 设 定 。 





。 如 果 自 己 伺服 静态 文件 ， 一 定 要 森 用 能 把 静态 文件 当做 代码 执行 的 处 理 程序 ， 如 Apache 的 mod_php。 








难道 你 想 让 用 户 随 意 执行 精心 制作 的 文件 中 的 代码 ? 











。 如 果 不 遵 守 安全 最 佳 实践 ，Django 对 上 传媒 体 的 处 理 有 些 漏洞 。 比 如 说 ， 如 果 HTML 文件 包含 有 效 
的 PNG 首部， 随后 是 恶意 HIML 代码 ， 那 么 上 传 时 会 把 它 视 作 图 像 。 对 Django 用 来 处 理 ImageField 
的 图 像 库 (Pillow) 来 说 ， 这 个 文件 能 通过 验证 。 演 染 时 ， 这 个 文件 可 能 会 作为 HTML 显示 ， 这 取决 
于 Web 服务 器 的 类 型 和 配置 。 框 架 层 虽 然 没 有 万 全 之 策 ， 无 法 验证 所 有 用 户 上 传 的 文件 



























































容 ， 但 是 我 们 可 以 做 几 件 事 ， 降低 被 攻击 的 风险 : 








包含 什么 内 


1. 使 用 单独 的 顶级 域名 或 二 级 域名 伺服 用 户 上 传 的 文件 能 避免 其 中 一 类 攻击 ， 例 如 同 源 策略 阻拦 
的 攻击 (如 跨 站 脚本 攻击 ) 。 假 如 你 的 网 站 部 署 在 example.com 域名 上 ， 可 以 在 usercontent-ex- 
ample.com 上 伺服 上 传 的 文件 (通过 MEDIA_URL 设置 设 定 ) ， 而 不 一 定 非得 在 二 级 域名 (如 

















usercontent.example.com) 上 伺服 。 











2， 此 外 ， 应 用 程序 可 以 定义 一 个 白 名 单 ， 指 明 允 许 用 户 上 传 的 文件 扩展 名 ， 然 后 














中， 只 伺服 那些 文件 。 


19.2 其 他 安全 建议 














了 配置 Web 服务 


























。 虽然 Django 自 带 了 稳固 的 安全 保护 措施 ， 但 是 依然 要 采用 正确 的 方式 部 署 应 用 程序 ， 利 
































器 、 操 作 系统 和 其 他 组 件 提 供 的 安全 保护 措施 。 

















Web 服务 








。 记得 把 Python 代码 放 在 Web 服务 器 的 文档 根 目 录 之 外 。 这 样 能 避免 不 小 心 以 纯 文 本 伺服 (或 执 





行 ) Python 代码 。 
。 谨慎 处 理 用 户 上 传 的 文件 。 











。 Django 不 限制 验证 用 户 身 份 的 次 数 。 为 了 防止 暴力 攻击 身份 验证 系统 ， 可 以 考虑 通过 Django 插件 或 





Web 服务 器 模块 限制 这 种 请 求 的 次 数 。 
。 保护 好 SECRET_KEY 设置 。 
。 最 好 使 用 防火 墙 限 制 对 缓存 系统 和 数据 库 的 访问 。 
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19.2.1 安全 问题 存档 


Django 的 开发 团队 坚定 承诺 ， 他 们 会 负责 报告 揭露 安全 相关 的 问题 。 这 一 点 在 Django 的 安全 策略 中 有 体 
现 。 























作为 这 个 承诺 的 一 部 分 ， 他 们 维护 着 已 经 修正 和 揭露 出 来 的 问题 列表 。 最 新 的 列表 参见 Django 文档 。 











19.2.2 加 密 签 名 





Web 应 用 程序 安全 性 的 黄金 法 则 是 ， 绝 不 信任 来 自 不 可 信 源 的 数据 。 有 时 ， 可 能 需要 通过 不 可 信 的 媒介 传递 
数据 。 此 时 ， 可 以 加 密 签名 要 传递 的 数据 ， 因 为 只 要 算 改 就 能 发 现 。 


根据 Web 应 用 程序 的 常见 需求 ，Django 提供 了 用 于 签名 的 低层 API， 以 及 用 于 设 定 和 读 取 签名 cookie 的 高 
层 API。 


























A/ 


六 


下 述 情况 也 外 


CC 
型 
Ne 

沪 
ny 


。 生成 “恢复 我 的 账号 " URL， 发 给 忘记 密码 的 用 户 。 
。 确保 隐藏 的 表单 字段 中 的 数据 没有 被 自 改 。 
。 生成 一 次 性 保密 URL， 用 于 临时 访问 受 保护 的 资源 。 例 如 ， 下 载 用 户 付费 购买 的 文件 。 
























































保护 SECRET_KEY 





使 用 startproject 命令 新 建 Django 项 目 时 ， 自 动 生成 的 settings.py 文件 把 SECRET_KEY 设 为 一 个 随机 值 。 
这 个 值 是 保护 签名 数据 的 关键 ， 一 定 要 保护 好 ， 如 果 被 攻击 者 获取 ， 就 能 用 它 生成 签名 数据 。 


使 用 低层 API 


Django 提供 的 签名 方法 在 django.core.signing 模块 中 。 若 想 签名 一 个 值 ， 先 实例 化 一 个 Signer 实例 : 





>>> from django.core.signing import Signer 
>>> signer = Signer() 

>>> value = signer.sign('My string') 

>>> value 

"My string:GdMGD6HNQ_qdgxYP8yBZAdAIV1w' 








签名 附加 到 字符 串 的 末尾 ， 通 过 冒号 与 原 字符 串 分 开 。 可 以 使 用 unsign 方法 获取 原 值 : 


>>> original = signer.unsign(value) 
>>> original 
"My string' 


一 日 签名 或 原 值 以 某 种 方式 修改 了 ， 抛 出 django.core.signing.BadSignature 异常 : 


>>> from django.core import signing 
>>> VaLue += 'm' 
>>> try: 
original = signer.unsign(value) 
. except signing.BadSignature: 
print("Tampering detected!") 

















默认 情况 下 ，Signer 类 使 用 SECRET_KEY 设置 生成 签名 。 如 果 想 使 用 其 他 密令 ， 把 它 传 给 Signer 构造 方法 : 
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>>> signer = Signer('my-other-secret') 
>>> value = signer.sign('My string') 
>>> value 

'My string:EkfQJafvGyiofrdGnuthdxImIJw' 

















django.core.signing.Signer 返回 一 个 签名 实例 ， 使 用 key 生成 签名 ， 使 用 sep 分 隔 原 值 和 签名 。sep 的 值 不 





能 在 对 URL 安全 的 base64 字母 表 (包括 字母 、 数 字 、 连 字符 和 下 划 线 ) 中 。 





使 用 salt 参数 


如 果 不 希 望 相同 的 字符 串 每 次 签名 都 得 到 相同 的 结果 ， 可 以 使 用 Signer 构造 方法 的 可 选 参数 salt。 此 时 ， 





salt 和 SECRET_KEY 都 会 传 给 计算 签名 的 函数 。 


>>> signer = Signer() 

>>> signer.sign('My string') 

"My string:GdMGD6HNQ_qdgxYP8yBZAdAIV1w' 

>>> signer = Signer(salt='extra') 

>>> signer.sign('My string') 

"My string:Ee7vGi-ING6n02gkcJ-QLHg6vFw' 

>>> signer.unsign('My string:Ee7vGi-ING6n02gkcJ-QLHg6vFw') 
"My string' 





























加 盐 后 ， 不 同 的 签名 放 在 不 同 的 命名 空间 中 。 一 个 命名 空间 〈 使 用 一 个 盐 值 ) 中 的 签名 不 能 用 于 验证 使 用 不 

















同 盐 值 的 另 一 个 命名 空间 中 的 纯 文 本 。 这 样 能 避免 攻击 者 在 盐 值 不 同 的 地 方 使 用 同一 个 签名 。 





与 SECRET_KEY 不 同 ， 盐 值 无 需 保 密 。 


验证 加 了 时 间 戳 的 值 








TimestampSigner 是 Signer 的 子 类 ， 在 值 后 面 附加 一 个 签名 的 时 间 戳 。 这 样 能 胡 




















认 签 名 的 值 是 不 是 在 特定 的 











时 间 段 内 创建 的 。 





>>> from datetime import timedelta 

>>> from django.core.signing import TimestampSigner 
>>> signer = TimestampSigner() 

>>> value = signer.sign('hello') 

>>> value 
'hello:1NMg5H:oPVuCqlJWmChm1irA2lyTUtelC-c' 

>>> signer .unsign(value) 

'hello' 

>>> signer.unsign(value, max_age=10) 


SignatureExpired: Signature age 15.5289158821 > 10 seconds 
>>> signer.unsign(value, max_age=20) 

'hello' 

>>> signer .unsign(value, max_age=timedelta(seconds=20)) 
'hello' 














sign(value) 对 value 签名 ， 并 附加 当前 时 间 惟 。unsign(vatue，max_age=None) 检查 value 是 否 在 max_age 秒 
之 前 签名 ， 如 果 不 是 ， 抛 出 SignatureExpired 异常 。max_age 参数 的 值 可 以 是 一 个 整数 或 一 个 date- 








time.timedelta 对 象 。 
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保护 复杂 的 数据 结构 














如 果 想 保护 列表 、 元 组 或 字典 ， 可 以 使 用 签名 模块 中 的 dumps 和 Loads 函数 。 这 两 个 函数 模拟 Python 的 pick- 
le 模块 ， 不 过 背后 使 用 的 序列 化 方式 是 JSON。JSON 利用 pickle 格式 ， 即 便 SECRET_KEY 被 盗 ， 攻 击 者 也 无 法 
随意 执行 命令 。 








>>> from django.core import signing 

>>> value = signing.dumps({"foo": "bar"}) 

>>> value 
‘eyJmb28i0iJiYXIifQ:1NMg1b:zGcDE4-TCkaeGzLeW9UQwZesciI' 
>>> signing.loads(value) 

{'foo': 'bar'} 





如 果 传 人 一 个 元 组 ， 使 用 signing.loads(object) 能 得 到 一 个 列表 ， 这 是 JSON 的 天 然 特 性 (不 区 分 列表 和 元 
组 ) : 


>>> from django.core import signing 

>>> value = signing.dumps(('a','b','c')) 
>>> signing.loads(value) 

| | 


19.2.3 安全 中 间 件 


区 


如 果 部 署 环境 允许 ， 通 常 最 好 让 前 端 Web 服务 器 负责 执行 SecurityMiddleware 提供 的 功能 。 
这 样 ， 不 由 Django 伺服 的 请 求 (例如 静态 媒体 文件 或 用 户 上 传 的 文件 ) 与 由 Django 伺服 的 请 
求 具有 相同 的 保护 措施 。 


django.middleware.security.SecurityMiddleware 为 请 求 - 响 应 循环 增加 了 几 项 安全 措施 ， 可 以 通过 下 述 设置 
单独 启用 或 禁用 : 

® SECURE_BROWSER_XSS_FILTER 

® SECURE CONTENT_TYPE_NOSNIFF 

®。 SECURE HSTS_INCLUDE_ SUBDOMAINS 

。 SECURE_HSTS_SECONDS 

® SECURE REDIRECT_EXEMPT 

®。 SECURE_SSL_HOST 


。 SECURE_SSL_REDIRECT 


关于 安全 方面 的 首部 ， 以 及 这 些 设置 的 说 明 ， 参 见 第 17 章 。 


19.3 接 下 来 


下 一 章 扩充 第 1 章 中 的 快速 安装 指南 ， 探 讨 Django 的 一 些 其 他 安装 和 配置 方式 。 
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第 20 章 安装 Django 的 其 他 方式 





本 章 介绍 一 些 安装 和 维护 Django 的 其 他 方式 。 首 先 ， 说 明 使 用 SQLite 之 外 的 数据 库 时 如 何 配置 ， 然 后 介绍 
如 何 升 级 Django， 以 及 自己 动手 安装 Django 的 方式 。 最 后 ， 介 绍 如 何 安 装 Django 的 开发 版 本 ， 以 防 你 想 试 
验 Django 最 新 开发 的 功能 。 




















20.1 使 用 其 他 数据 库 





























如 果 想 使 用 Django 的 数据 库 API 所 提供 的 功能 ， 要 确保 运行 着 数据 库 服 务 器 。Django 支持 很 多 不 同 的 数据 
库 服务 器 ， 官 方 提供 支持 的 有 PostgreSQL、MySQL、Oracle 和 SQLite。 


第 21 章 将 详细 说 明 在 Django 中 如 何 连 接 这 些 数据 库 ， 但 是 本 书 不 会 说 明 如 何 安装 各 个 数据 库 。 安 装 方法 参 
见 各 数据 库 网 站 中 的 文档 。 
如 果 你 开发 的 是 小 型 项 目 ， 或 者 不 打算 部 署 到 生产 环境 ，SQLite 通常 是 最 佳 选择 ， 因 为 它 无 需 运 行 单独 的 服 
务 器 。 然 而 ，SQLite 与 其 他 数据 库 有 很 多 差异 ， 因 此 如 果 你 在 开发 重要 的 项 目 ， 建 议 你 使 用 计划 在 生产 环境 
使 用 的 数据 库 。 


除了 数据 库 后 端 之 外 ， 还 要 安装 相应 的 Python 数据 库 绑 定 。 
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。 如 果 使 用 PostgreSQL， 要 安装 postgresql_psycopg2 包 。 详 细 技 术 细节 参见 21.2 和 节 。Windows 用 户 可 以 
使 用 非 官方 的 编译 版 本 。 
如 果 使 用 MySQL， 要 安装 MySQL-python 包 (1.2.1p2 或 以 上 版 本 ) 。 详 情 参见 21.3 节 。 
。 如 果 使 用 SQLite， 请 阅读 21.4 节 。 



















































































。 如 果 使 用 Oracle， 要 安装 cx_Oracle。 所 支持 的 Oracle 和 cx_0racte 版 本 ， 以 及 其 他 关于 Oracle 后 端的 
信息 ， 参 见 21.5 市 。 
。 如 果 使 用 非 官 方 的 第 三 方 后 端 ， 请 参阅 相应 的 文档 ， 了 解 更 多 信息 。 









































如 果 想 使 用 Django 的 manage.py migrate 命令 自动 为 模型 创建 数据 库 表 (首次 安装 Django 和 创建 项 目 后 ) ， 
要 确保 Django 有 权限 创建 或 修改 数据 库 中 的 表 ， 如 果 计 划 自 己 动 手 创建 数据 库 表 ， 只 需 把 SELECT、INSERT、 
UPDATE 和 DELETE 权限 赋予 Django。 使 用 这 些 权 限 创建 好 数据 库 用 户 之 后 ， 要 在 项 目的 设置 文件 中 设 定 详细 
信息 ， 详 情 参 见 DATABASES 设置 的 文档 。 










































































如 果 想 使 用 Django 的 测试 框架 测试 数据 库 查 询 ， 要 赋予 Django 创建 测试 数据 库 的 权限 。 











20.2 手动 安装 Django 


1. 从 Django 项 目 网 站 的 下 载 页 面 下 载 最 新 发 布 版 。 


2， 解 压 下 载 的 文件 〈 例 如 tar xzvf Django-X.Y.tar.gz， 其 中 X.Y 是 最 新 发 布 版 的 版 本 号 ) 。 如 果 使 用 的 
是 Windows， 可 以 使 用 命令 行 工具 bsdtar， 或 者 使 用 GUI 工具 (如 7-zip) 解压 。 


3. 进入 第 2 步 得 到 的 目录 (例如 cd Django-X.Y) 。 


4. 如 果 使 用 的 是 Linux、macO5S 或 其 他 Unix 变种 ， 在 shell 中 输入 命令 sudo python setup.py install。 
如 果 使 用 的 是 Windows， 以 管理 员 身 份 启动 命令 行 ， 然 后 运行 python setup.py install 命令 。 这 些 命 
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今 把 Django 安装 到 Python 的 site-packages 目录 中 。 


删除 旧版 本 


如 果 采 用 这 种 安装 方式 ， 一 定 要 先 删除 以 前 安装 的 Django (方法 参见 后 文 ) 。 否 则 ， 安 装 可 能 
会 出 错 ， 例 如 被 Django 删除 的 旧版 文件 仍然 存在 。 





20.3 升级 Django 


20.3.1 删除 旧版 Django 


升级 Django 之 前 要 先 把 旧版 本 删除 ， 然 后 再 安装 新 版 本 。 














如 果 Django 之 前 是 使 用 pip 或 easy_install 安装 的 ， 再 使 用 它们 安装 新 版 就 无 需 自己 动手 删除 ， 这 两 个 工 
具 会 自动 清理 旧版 。 




















如 果 之 前 是 自己 动手 安装 的 Django， 仓 载 也 不 麻烦 ， 只 需 从 Python 的 site-packages 目录 中 删除 django 目 
录 。 为 了 找到 需要 删除 的 目录 ， 可 以 在 shell (不 是 交互 式 Python 控制 台 ) 中 运行 下 述 命令 : 





python -c "import sys; sys.path = sys.path[1:]; import django; print(django.__path__)" 


20.4 安装 针对 特定 发 行 版 的 包 





若 想 检查 你 使 用 的 平台 /发 行 版 有 没有 官方 的 Django 包 (安装 程序 ) ， 参 阅 Django 文档 中 对 各 发 行 版 的 说 
明 。 针 对 特定 发 行 版 的 包 往往 能 自动 安装 依赖 ， 而 且 便于 升级 。 然 而 ， 这 些 包 很 少 有 Django 的 最 新 版 。 











20.5 安装 开发 版 


如 果 决 定 使 用 Django 的 最 新 开发 版 ， 一 定 要 紧 盯 开发 时 间 线 ， 还 要 关注 下 一 个 版 本 的 发 布 记 。 使 用 开发 版 的 
好 处 是 能 第 一 时 间 使 用 新 特性 ， 而 且 能 及 早 修改 代码 ， 应 对 新 版 本 。 (发 布 记 中 会 详 述 各 稳定 版 的 重要 变 
化 。) 


如 果 想 偶尔 升级 Django 代码 ， 获 取 最 近 修 正 的 缺陷 和 做 出 的 改进 ， 按 照 下 述说 明 操 作 : 












































1.， 确保 系统 中 安装 了 Git， 而 且 可 以 在 shell 中 使 用 Git 命令 。 (在 shell 中 输入 git help， 测 试 可 不 可 
用 。) 


2， 检 出 Django 的 主 开发 分 支 “trunk ”或 “master") ， 如 下 所 示 : 


git clone git://github.com/django/django.git django-trunk 





这 个 命令 会 在 当前 目录 中 创建 django-trunk 目录 。 
3. 确保 Python 解释 器 可 以 加 载 Django 的 代码 。 最 便利 的 方式 是 使 用 pip。 执 行 下 述 命 令 : 








sudo pip install -e django-trunk/ 


(如 果 使 用 virtualenv 或 者 Windows， 可 以 省 略 sudo。) 这 个 命令 的 作用 是 让 Django 的 代码 可 以 导 
入 ， 并 让 django-admin 实用 命令 可 用 。 至 此 结束 | 
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不 要 运行 sudo python setup.py install 命令 ， 因 为 第 3 步 那 个 命令 已 经 执行 相关 操作 了 。 想 
升级 Django 源码 时 ， 只 需 在 django-trunk 目录 中 运行 git pull 命令 ，Git 将 自动 下 载 所 有 改 
动 。 

20.6 接 下 来 


下 一 章 详细 说 明 如 何 使 用 不 同 的 数据 库 运行 Diango。 
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本 章 详细 说 明 如 何在 Django 中 使 用 各 个 支持 的 关系 数据 库 ， 还 会 给 出 一 些 连 接 旧 数据 库 的 注意 事项 和 小 技 
巧 。 


21.1 通用 说 明 





Django 已 经 尽力 多 支持 各 个 数据 库 后 端的 功能 ， 但 是 数据 库 后 端 之 间 是 有 差异 的 ， 因 此 Django 开发 者 会 有 
选择 性 地 为 特定 的 功能 提供 支持 ， 而 且 会 选择 安全 的 方式 实现 。 


本 章 说 明 在 使 用 Django 的 过 程 中 可 能 用 到 的 一 些 功能 。 当 然 ， 说 得 再 细致 也 不 能 代替 各 数据 库 后 端的 文档 或 
参考 手册 。 


















































21.1.1 持久 连接 


持久 连接 的 消耗 更 小 ， 无 需 每 次 请 求 都 重新 与 数据 库 建立 连接 。 持 久 连 接 的 最 长 时 间 由 CONN_MAX_AGE 设置 控 
制 。 各 数据 库 可 以 分 别 设 定 CONN_MAX_AGE 值 。 默 认 值 为 6， 即 使 用 旧 的 行为 ， 每 次 请 求 结 束 后 断 开 连接 。 若 
想 打开 持久 连接 ， 把 CONN_MAX_AGE 设 为 一 个 表示 秒 数 的 正 数 。 如 果 想 一 直 持久 连接 ， 把 值 设 为 None。 






























































连接 管理 





首次 查询 数据 库 时 ，Django 连接 到 数据 库 。 随 后 ， 保 持 连 接 ， 供 后 续 查 询 复 用 。 超 过 CONN_MAX_AGE 定义 的 最 
大 时 长 ， 或 者 不 再 需要 使 用 时 ，Django 断 开 与 数据 库 的 连接 。 


具体 而 言 ， 需 要 查询 数据 库 而 连接 尚未 建立 时 ， 不 管 是 首次 查询 ， 还 是 之 前 的 连接 断 开 了 ，Django 会 自动 建 
立 连 接 。 


每 次 请 求 开始 时 ， 如 果 连 接 的 时 间 超 过 了 允许 的 最 大 时 长 ，Dijango 会 断 开 连接 。 如 果 连 接 空闲 一 段 时 间 之 后 
才 被 断 开 ， 应 该 把 CONN_MAX_AGE 的 值 设 得 小 一 点 儿 ， 以 防 Django 使 用 已 近 被 数据 库 服务 器 终止 的 连接 。 


(这 个 问题 可 能 只 影响 流量 非常 小 的 网 站 。) 


每 次 请 求 结束 时 ， 如 果 连 接 超过 了 人 允许 的 最 大 时 长 ， 或 者 处 于 无 法 恢复 的 错误 状态 ，Django 会 将 其 断 开 。 如 
果 在 处 理 请 求 的 过 程 中 出 现 了 数据 库 错误 ，Dijango 会 检查 连接 是 否 依 然 可 用 ， 如 果 不 可 用 就 将 其 断 开 。 因 
此 ,数据库 错误 最 多 影响 一 个 请 求 ， 一 旦 连接 不 可 用 ， 下 一 个 请 求 会 重新 连接 。 






















































































































































































因为 每 个 线程 都 维护 着 一 个 连接 ， 所 以 使 用 多 少 线程 最 少 要 同时 有 多 少 个 连接 。 


有 时 ， 多 数 视 图 无 法 访问 数据 库 ， 这 可 能 是 因为 数据 库 在 外 部 系统 中 ， 或 者 是 缓存 在 起 作用 。 遇 到 这 种 情 
况 ， 应 该 把 CONN_MAX_AGE 设 为 较 小 的 值 ， 或 者 干脆 设 为 6， 因 为 无 法 复 用 的 连接 无 需 再 去 维护 了 。 这 样 ， 数 
据 库 的 同时 连接 数 也 变 小 了 。 


开发 服务 器 为 要 处 理 的 每 个 请 求 新 建 一 个 线程 ， 为 的 是 避免 持久 连接 。 别 在 开发 过 程 中 建立 持久 连接 。 


Django 与 数据 库 建 立 连接 时 ， 会 根据 所 用 的 数据 库 后 端 设 定 适 当 的 参数 。 如 果 使 用 持久 连接 ， 不 会 每 次 请 求 
都 重复 设 定 参数 。 如 果 想 修改 参数 ， 例 如 连接 的 隔离 级 别 或 时 区 ， 应 该 在 每 次 请 求 结束 后 还 原 成 Django 的 默 
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认 值 ， 迫 使 每 次 请 求 开 始 时 使 用 恰当 的 值 ， 或 者 禁用 持久 连接 。 


21.1.2 编码 








Django 假定 所 有 数据 库 都 使 用 UTF-8 编码 。 使 用 其 他 编码 可 能 导致 意料 之 外 的 行为 ， 例 如 对 Django 有 效 的 
数据 可 能 导致 数据 库 报错 ， 提 醒 值 太 长 。 正 确 设置 数据 库 的 方法 参见 后 文 对 各 个 数据 库 的 说 明 。 















































21.2 PostgreSQL 说 明 
Django 支持 PostgreSQL 9.0 及 以 上 版 本 。 为 此 ， 要 使 用 Psycopg2 2.0.9 或 以 上 版 本 。 


21.2.1 优化 PostgreSQL 的 配置 


连接 数据 库 时 ，Django 需要 下 述 参数 : 





。 client encoding. 'UTF8 


。 default_transaction_isolation: 使 用 默认 值 'read committed' ， 或 者 连接 选项 中 设 定 的 值 (参见 下 
文 ) 。 


。 timezone: USE_TZ 设置 为 True 时 为 'UTC' ， 和 否则 使 用 TIME_ZONE 设置 的 值 。 


















































如 果 这 些 参数 已 经 设 为 正确 的 值 ，Django 直接 拿 来 用 ， 不 用 在 每 次 连接 时 重新 设 定 ， 这 样 能 稍微 提升 一 点 性 
能 。 这 些 参数 可 以 在 postgresql.conf 文件 中 配置 ， 如果 想 更 细致 ， 为 各 个 数据 库 用 户 配置 不 同 的 值 ， 使 用 
ALTER ROLE。 













































































如 果 不 设 定 这 些 参数 ，Django 也 能 与 数据 库 连 接 ， 只 不 过 每 次 连接 时 都 要 做 额外 的 查询 ， 设 定 这些 参 数 。 





21.2.2 隔离 级 别 





与 PostgreSQL 自身 一 样 ，Django 默认 使 用 的 隔离 级 别 是 READ COMMITTED。 如 果 需 要 更 高 的 隔离 级 别 ， 例 如 
REPEATABLE READ 或 SERIALIZABLE， 在 DATABASES 设置 的 OPTIONS 选项 中 配置 : 





import psycopg2.extensions 


DATABASES = { 
i 
'OPTIONS': { 
'isolation_level': psycopg2.extensions.ISOLATION_LEVEL_SERIALIZABLE, 
}, 
} 


在 较 高 的 隔离 级 别 下 ， 应 用 程序 要 做 好 准备 ， 处 理 序列 化 失败 抛 出 的 异常 。 这 个 选项 针对 高 级 用 户 。 






































21.2.3 索引 varchar 和 text 列 








Django 通常 为 指定 了 db_index=True 的 模型 字段 输出 一 个 CREATE INDEX 语句 。 然 而 ， 如 果 数 据 库 字段 的 类 型 
是 varchar 或 text (例如 CharField、FileField 或 TextFieLd) ，Django 会 使 用 适当 的 PostgreSQL 运算 符 类 
额外 再 为 字段 创建 一 个 索引 。 为 了 能 正确 执行 包含 LIKE 运算 符 的 SQL ( 即 contains 和 startswith 查询 类 
型 ) ， 必 须要 有 那个 额外 的 索引 。 
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21.3 MySQL 说 明 


21.3.1 支持 的 版 本 
Django 支持 MySQL 5.5 及 以 上 版 本 。 




















Django 的 inspectdb 功能 使 用 information_schema 数据 库 ， 这 里 包含 关于 所 有 数据 库 模 式 的 详细 数据 。 


Django 假定 数据 库 支 持 Unicode (UTF-8 编码 ) ， 把 事务 和 参照 完整 性 都 委托 给 数据 库 。 值 得 注意 的 是 ， 使 
用 MyISAM 存储 引擎 时 ，MySQL 并 不 强制 实施 事务 和 参照 完整 性 (参见 下 一 节 ) 。 


























21.3.2 存储 引擎 
MySQL 有 多 种 存储 引擎 。 默 认 采 用 的 存储 引擎 可 以 在 服务 器 配置 中 修改 。 


在 MySQL 5.5.4 之 前 ， 默 认 的 存储 引擎 是 MYISAM。 这 个 存储 引擎 的 主要 缺点 是 不 支持 事务 和 外 键 约束 。 但 
它 也 有 优点 ， 在 MySQL 5.64 之 前 ， 它 是 唯一 支持 全 文 索引 和 搜索 的 引擎 。 


从 MySQL 5.5.5 开始 ， 默 认 的 存储 引擎 变 成 了 InnoDB 。 这 个 引擎 完全 支持 事务 和 外 键 引 用 。 目 前 ， 这 个 引擎 
可 能 是 最 好 的 选择 。 然 而 要 注意 ， 重 启 MySQL 后 ，InnoDB 的 自 增 计 数 器 会 丢失 ， 因 为 它 无 法 记 住 AuTO_IN- 
CREMENT 的 值 ， 只 能 重建 为 max(id)+1。 这 可 能 导致 意外 重用 AutoField 的 值 。 




































































把 现 有 项 目 升 级 到 MySQL 5.5.5 之 后 ， 如 果 新 增 了 数据 表 ， 要 确保 所 有 表 使 用 相同 的 存储 引擎 ( 即 MyISAM 
或 InnoDB) 。 极 为 突出 的 是 ， 如 果 是 有 ForeignKey 的 两 个 表 ， 运 行 migrate 命令 时 可 能 出 现下 述 错误 : 












































_mysql_exceptions.OperationalError: ( 
1005, "Can't create table '\\db_name\\.#sql-4a8_ab' (errno: 150)" 
) 


21.3.3 MySQL DB API 驱动 





Python Database API 在 PEP 249 中 说 明 。 有 三 个 重要 的 MySQL 驱动 实现 了 这 个 API: 














。 MySQLdb 是 一 个 原生 驱动 ， 这 十 年 来 一 直 由 Andy Dustman 开发 和 提供 支持 。 

。 mysqlclient 是 MySQLdb 的 派生 版 本 ， 主 要 特色 是 支持 Python 3， 而 且 可 以 直接 替代 MySQLdb 。 截 至 

目前 ， 在 Django 中 使 用 MySQL 推荐 使 用 这 个 驱动 。 

。 MySQL Connector/Python 由 Oracle 推出 ， 是 使 用 纯 Python 实现 的 驱动 ， 无 需 MySQL 客户 端 库 和 
Python 标准 库 之 外 的 模块 。 




















































































































这 些 驱动 对 线程 都 是 安全 的 ， 而 且 都 提供 了 连接 池 。 目 前 ，MySQLdb 是 唯一 不 支持 Python 3 的 驱动 。 











除了 DB API 驱动 之 外 ， 为 了 让 Django 的 ORM 能 访问 数据 库 驱 动 ， 还 需要 适配器 (adapter) 。Django 为 
MySQLdb 和 mysqlclient 提供 了 适配器 ， 而 MySQL Connector/Python 自 带 了 适配器 。 











mySQLdb 


Django 要 求 使 用 MySQLdb 1.2.1p2 或 以 上 版 本 。 





如 果 使 用 的 过 程 中 报错 ImportError: cannot import name ImmutabLeSet， 说 明 你 安装 的 MySQLdb 中 sets.py 
文件 过 时 了 ， 与 Python 2.4 及 以 上 版 本 自 带 的 同名 内 置 模块 有 冲突 。 修 正 的 方法 是 ,确认 安装 的 MySQLdb 
是 1.2.1p2 或 以 上 版 本 ， 然 后 删除 旧版 在 MySQLdb 目录 中 遗留 的 sets.py 文件 。 
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MySQLdb 无 法 正确 把 日 期 字符 串 转 换 成 datetime 对 象 ， 这 是 已 知 的 问题 。 具 体 而 言 ， 日 期 字符 串 
0000-00-00 对 MySQL 而 言 是 有 效 的 ， 但 是 MySQLdb 会 将 其 转换 成 None。 


















































也 就 是 说 ， 使 用 loaddata/dumpdata 处 理 包含 0999-99-09 值 的 行 时 要 小 心 ， 因 为 它们 会 被 转换 成 None。 


截至 目前 ，MySQLdb 的 最 新 版 本 (1.24) 还 未 支持 Python 3。 若 想 在 Python 3 中 使 用 MySQLdb， 只 能 安装 
mysqlclient 。 





mysdqdlclient 


Django 要 求 使 用 mysqlclient 1.3.3 或 以 上 版 本 。 注 意 ，mysqlclient 不 支持 Python 3.2。 除 了 对 Python 3.3+ 的 
支持 ，mysqlclient 的 行为 基本 上 与 MySQLdb 一 致 。 


MySQL Connector/Python 














MySQL Connector/Python 可 从 这 个 页 面 下 载 。1.1.X 及 以 上 版 本 包含 Django 适配器 。 这 个 驱动 可 能 不 支持 
Django 最 近 发 布 的 版 本 。 


21.3.4 时 区 定义 








如 果 打 算 使 用 Django 的 时 区 功能 ， 使 用 mysql_tzinfo_to_sql 把 时 区 数据 表 加 载 到 MySQL 数据 库 中 。 一 个 
MySQL 服务 器 只 需 做 一 次 ， 不 用 每 个 数据 库 都 加 载 。 


























21.3.5 创建 数据 库 


可 以 在 命令 行 工具 中 使 用 下 述 SQL 创建 数据 库 : 





CREATE DATABASE <dbname> CHARACTER SET utf8; 








这 样 所 有 表 和 列 默认 都 将 使 用 UTF-8。 





排序 规则 设置 





列 的 排序 规则 (collation) 控制 着 存储 数据 的 顺序 ， 以 及 把 哪些 字符 串 视 为 相等 的 。 排 序 规则 可 以 在 整个 数据 
库 层 设 定 ， 也 可 以 在 各 个 表 和 列 上 设 定 。MySQL 文档 中 有 详细 说 明 。 不 管 在 哪里 设 定 ， 都 要 直接 操纵 数据 
库 表 ， 因 为 Django 没有 在 模型 定义 中 提供 设 定 方式 。 

















区 


JTF-8 编码 的 数据 库 默 认 使 用 utf8_general_ci 排序 规则 。 在 这 个 规则 下 ， 比 较 字 符 吕 相等 性 时 不 区 分 大 小 
写 。 也 就 是 说 ， 数 据 库 把 "Fred" 和 "freD" 视 为 相等 的 字符 串 。 如 果 在 一 个 字段 上 设 定 了 唯一 性 约束 ， 就 无 
法 在 同一 列 中 插入 "aa" 和 "AA"， 因 为 在 默认 的 排序 规则 下 二 者 是 相等 的 (也 就 不 是 唯一 的 ) 。 


很 多 情况 下 使 用 这 个 默认 值 没 有 问题 。 然 而 ， 如 果 确 实 想 在 某 列 或 某 个 表 中 使 用 区 分 大 小 写 的 比较 方式 ， 可 
以 把 列 或 表 的 排序 规则 改 为 utf8_bin。 注 意 ， 使 用 MySQLdb 1.2.2 时 ，Django 的 数据 库 后 端 从 数据 库 的 字符 
字段 中 获取 的 值 都 是 字 节 字符 串 (而 不 是 Unicode 字符 串 ) 。 这 与 Django 始终 返回 Unicode 字符 串 的 做 法 完 
全 不 同 。 



















































































如 果 让 数据 表 使 用 utf8_bin 排序 规则 ， 开 发 者 要 负责 处 理 得 到 的 字 节 字符 串 。 多 数 情况 下 ，Django 自身 能 顺 
利 处 理 这 样 的 列 (不 含 contrib.sessions Session 和 contrib.admin LogEntry 表 ， 参 见 下 文 ) ， 但 是 你 编写 

的 代码 也 做 好 调用 django.utils.encoding.smart_text() 的 准备 ， 以 防 需 要 处 理 一 致 的 数据 ， 因 为 Django 不 
会 为 你 代劳 (数据库 后 端 层 与 模 弄 处理 层 是 分 开 的 ， 因 此 遇 到 这 种 情况 时 数据 库 层 不 知道 要 转换 ) 。 



































使 用 MySQLdb 1.2.1p2 时 ， 即 便 使 用 utf8_bin 排序 规则 ，Django 标准 的 CharField 字段 仍然 返回 Unicode 字 
符 串 。 然 而 ，TextFietLd 字段 返回 的 是 array.array 实例 (出 自 Python 标准 库 中 的 array 模块 ) 。 对 此 ， 
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Django 也 是 无 能 为 力 ， 原因 同上 ， 从 数据 库 中 读 取 数 据 时 没有 足够 的 信息 ， 无 法 转换 。MySQLdb 1.2.2 修正 
了 这 个 问题 ， 所 以 ， 如 果 想 在 utf8_bin 排序 规则 下 使 用 TextFieLd， 请 升级 到 1.2.2 版 ， 然 后 按照 前 文 所 述 的 
方式 处 理 字 节 字符 串 (不 是 很 难 ) 。 


使 用 MySQLdb 1.2.1p2 或 1.2.2 时 ， 你 可 能 会 让 部 分 表 使 用 utf8_bin 排序 规则 ， 但 是 django.contrib.ses- 

sions.modeLs.Session 表 (通常 称 为 django_session) 和 django.contrib.admin.models.LogEntry 表 (通常 称 

为 django_admin_Log) 仍然 要 使 用 (默认 的 ) utf8_general_ci 排序 规则 。 根 据 MySQL 文档 中 的 “Unicode 

Character Sets” 一 文 ， 与 utf8_unicode_ci 相 比 ， 在 utf8_general_ci 排序 规则 下 比较 的 速度 更 快 ， 但 是 准确 性 

稍 差 一 些 。 如 果 你 的 应 用 程序 能 接受 这 一 点 ， 应 该 使 用 utf8_generaL_ct， 因 为 它 速 度 更 快 ， 如 果 不 能 接受 
(例如 需要 使 用 德语 字典 顺序 ) ， 应 该 使 用 utf8_unicode_ci， 因 为 它 更 准确 。 


模型 表单 集 (formset) 以 区 分 大 小 写 的 方式 验证 唯一 性 字段 。 因 此 ， 使 用 不 区 分 大 小 写 的 排序 
规则 时 ， 如 果 唯 一 性 字段 中 的 值 具 有 大 小 写 不 同 是 能 通过 验证 的 ， 但 是 调用 save() 时 会 抛 出 


IntegrityError 异常 。 












































21.3.6 连接 数据 库 

















连接 设置 按照 下 述 顺序 使 


ai 


。 OPTIONS 
。 NAME, USER, PASSWORD, HOST, PORT 
。 MySQL 选项 文件 





也 就 是 说 ， 如 果 在 OPTIONS 中 设 定 了 数据 库 的 名 称 ， 它 的 优先 级 比 NAME 高 ， 还 会 覆盖 MySQL 选项 文件 中 的 
设置 。 下 述 示例 配置 使 用 MySQL 选项 文件 : 


# settings.py 
DATABASES = { 
'default': { 
'ENGINE': 'django.db.backends.mysql', 
'OPTIONS': {'read _ default file': '/path/to/my.cnf',}, 


} 


# my.cnf 

[client] 

database = NAME 

user = USER 

password = PASSWORD 
default-character-set = utf8 





可 能 用 到 的 还 有 MySQLdb 的 其 他 连接 选项 ， 例 如 ssl、iinit_command 和 sqL_mode。 详 情 参见 MySQLdb 文 
档 。 


21.3.7 创建 数据 表 
Django 生成 模式 时 不 指定 存储 引擎 ， 因 此 创建 的 表 使 用 为 数据 库 服务 器 配置 的 默认 存储 引擎 。 
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所 以 ， 把 数据 库 服务 器 的 默认 存储 引擎 设 为 想 用 的 引擎 是 最 简单 的 方法 。 
如 果 你 使 用 的 是 托管 服务 ， 无 法 修改 数据 库 服务 器 的 默认 存储 引擎 ， 有 以 下 几 个 选择 : 
































。 创建 表 之 后 执行 ALTER TABLE 语句 ， 转 换 成 新 的 存储 引擎 (例如 InnoDB) : 


ALTER TABLE <tablename> ENGINE=INNODB; 





如 果 有 大 量 表 ， 这 么 做 很 麻烦 。 
。 另 一 个 选择 是 在 创建 表 之 前 使 用 MySQLdb 的 init_command 选项 : 




















'OPTIONS' :{ 
'init_command': 'SET storage_engine=INNODB ' ， 


js 


这 种 方法 在 连接 数据 库 时 就 设 定 默 认 存储 引擎 。 创 建 表 之 后 应 该 把 这 个 选项 删除 ， 因 为 它 增 加 了 一 个 
查询 ， 而 这 个 查询 只 在 创建 表 时 需要 。 

















21.3.8 表 名 


MySQL (即便 是 最 新 版 本 ) 有 个 已 知 问题 : 在 特定 情况 下 执行 特定 的 SQL 语句 可 能 导致 表 名 的 大 小 写 发 生 
变化 。 如 果 可 能 ， 建 议 表 名 使 用 小 写字 母 ， 以 防 被 这 个 行为 影响 。Django 根据 模型 自动 生成 的 表 名 使 用 小 写 
字母 ， 因 此 通过 db_table 参数 覆盖 表 名 时 要 注意 这 一 点 。 









































21.3.9 保存 点 
Django ORM 和 MySQL (使 用 InnoDB 存储 引擎 时 ) 都 支持 数据 库 保 存 点 (savepoint) 。 


使 用 MyISAM 存储 引擎 时 要 注意 ， 事 务 API 中 与 保存 点 有 关 的 方法 可 能 导致 数据 库 出 错 。 这 是 因为 检测 
MySQL 数据库 ( 表 ) 使 用 哪 种 存储 引擎 是 个 耗费 资源 的 操作 ， 因 此 判定 在 检测 结果 中 不 值得 动态 转换 这 些 
方法 。 























21.3.10 某 些 字段 要 注意 的 事项 


字符 字段 





对 列 类 型 为 VARCHAR 的 字段 来 说 ， 如 果 为 字段 设 定 了 unique=True， 那 么 字段 中 最 多 能 存储 255 个 字符 。 受 影 
响 的 有 CharFieLd、SLugFieLd 和 CommaSeparatedIntegerField。 














时 间 和 日 期 时 间 字段 对 微 秒 的 支持 





MySQL 5.64 及 以 上 版 本 能 存储 微 秒 ， 前 提 是 定义 列 时 指定 包含 微 秒 〈 例 如 DATETIME(6)) 。 之 前 的 版 本 完全 
不 支持 。 此 外 ，MySQLdb 1.2.5 之 前 的 版 本 有 个 缺陷 ， 无 法 正确 在 MySQL 中 存储 微 秒 。 


即使 数据 库 服 务 器 支持 微 秒 ，Django 也 不 会 自动 更 新 现 有 列 ， 包 含 微 秒 。 如 果 想 在 现 有 数据 库 中 存储 微 秒 ， 
要 执行 下 述 命令 ， 自 己 动手 更 新 列 : 





















































ALTER TABLE ‘your_table. MODIFY ‘your_datetime column ”DATETIME(6) 





也 可 以 在 数据 迁移 中 执行 RunsQL 操作 。 














使 用 MySQL 5.6.4 或 以 上 版 本 ， 并 且 使 用 mysqlclient 或 MySQLdb 1.2.5 或 以 上 版 本 时 ， 新 建 的 DateTime- 
Field 或 TimeField 列 默 认 包 含 微 秒 。 
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时 间 戳 列 








如 果 使 用 旧 数 据 库 ， 包 含 TIMESTAMP 列 ， 必 须 设 定 USE_TZ = False， 以 防 数据 损坏 。inspectdb 命令 会 把 这 种 
类 型 的 列 映射 到 DateTimeFieLd 上 ; 如果 启 用 了 时 区 支持 ，MySQL 和 Django 都 会 尝试 把 时 间 戳 值 从 UTC 转 
换 成 本 地 时 间 。 

















使 用 Queryset.select_for_update() 锁定 行 














MySQL 不 支持 在 SELECT .FOR UPDATE 语句 中 使 用 NOWAIT 选项 。 如 果 设 定 了 nowait=True， 调 用 se- 
Lect_for_update() 时 会 抛 出 DatabaseError 异常 。 











自动 转换 类 型 可 能 导致 意外 结果 


查询 类 型 为 字符 串 但 实际 存储 整数 值 的 列 时 ， 在 比较 之 前 MySQL 会 把 表 中 所 有 类 型 的 值 强制 转换 成 整数 。 

如 果 表 中 包含 "abc" 或 "def" 这 样 的 值 ， 而 查询 条 件 是 WHERE mycolumn=06， 这 两 行 都 将 匹配 。 类 似 地 ，WHERE 
mycolumn=1 将 匹配 "abc1"。 因 此 ， 在 Django 中 定义 的 字符 串 类 型 字段 ， 在 查询 中 使 用 之 前 始终 会 被 转换 成 
字符 串 。 


如 果 你 自 定 义 的 模型 字段 直接 继承 自 Fleld， 而 且 和 覆盖 了 get_prep_vaLue() ， 或 者 使 用 extra() 或 raw()， 应 
该 确保 做 了 恰当 的 类 型 转换 。 

























































































21.4 SQLite 说 明 








如 果 应 用 程序 主要 用 于 读 取 数 据 ， 或 者 不 想 安 装 大 量 支 持 工 具 ， 在 开发 过 程 中 特别 适合 使 用 SQLite。 不 过 数 
据 库 服 务 器 之 间 存 在 着 差异 ， 有 些 SQLite 特有 的 差异 是 你 需要 知晓 的 。 











21.4.1 子 串 匹 配 和 大 小 写 





所 有 SQLite 版 本 在 匹配 某 些 类 型 的 字符 串 上 都 有 一 些 违背 直觉 的 行为 。 这 些 行 为 在 查询 集合 上 使 用 iexact 
或 contains 过 滤器 时 便 能 体现 出 来 。 这 些 行 为 分 为 两 种 情况 : 























1， 匹 配子 串 时 不 区 分 大 小 写 。 例 如 name__contains="aa" 过 滤器 能 匹配 "Aabb"。 


2， 精 确 匹 配 包含 ASCII 以 外 字符 的 字符 串 时 ， 即 便 在 查询 中 指定 了 不 区 分 大 小 写 的 选项 ， 仍 然 以 区 分 大 
小 写 的 方式 匹配 。 因 此 ， 在 这 种 情况 下 ，iexact 过 滤器 的 行为 与 exact 过 滤器 完全 一 样 。 















































SQLite 网 站 中 给 出 了 一 些 变通 方案 ， 但 是 Django 默认 的 SQLite 后 端 并 未 采用 ， 因 为 那些 方案 很 难 正确 集 
成 。 因 此 ，Dijango 提供 的 是 SQLite 的 默认 行为 。 想 以 不 区 分 大 小 写 的 方式 过 滤 ， 或 者 过 滤 子 串 时 要 知晓 这 
一 点 。 




















21.4.2 旧版 SQLite 和 CASE 表达 式 


SQLite 3.6.23.1 及 以 下 版 本 在 处 理 包 含 ELSE 和 算术 运算 的 CASE 表达 式 中 的 查询 参数 时 有 个 缺陷 。 


SQLite 3.6.23.1 在 2010 年 3 月 发 布 ， 而 针对 各 平台 的 二 进 制 分 发 版 本 如 今 大 都 包含 较 新 的 版 本 ， 不 过 Win- 
dows 的 Python 2.7 安装 程序 是 个 例外 。 














截至 目前 ， 针 对 Windows 的 最 新 版 本 (Python 2.7.10) 包含 SQLite 3.6.21。 这 个 问题 的 补救 措施 是 安装 
pysqLite2， 或 者 从 SQLite 网 站 中 下 载 较 新 版 本 的 sqLite3.dLL， 把 旧版 蔡 换 掉 (默认 安装 到 C:\Python27\ 
DLLs 文件 夹 中 ) 。 
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21.4.3 使 用 SQLite DB-API 2.0 驱动 的 较 新 版 本 











如 果 安 装 有 pysqLite2，Dijango 将 优先 使 用 ， 蔡 代 Python 标准 库 中 自 带 的 sqlite3。 









































这 样 ， 如 果 需 要 ， 可 以 把 DB-API 2.0 接口 或 SQLite 3 自身 升级 到 比 Python 二 进 制 分 发 文件 中 自 带 的 更 新 的 
版 本 。 


21.4.4 数据 库 锁定 错误 





SQLite 是 轻 量 级 数据 库 ， 不 支持 大 量 并 发 。 如 果 出 现 0perationalError: database is Locked 错误 ， 说 明 应 
用 程序 的 并 发 数 超过 了 SQLite 默认 配置 所 能 处 理 的 数量 。 这 个 错误 表明 某 个 线程 或 进程 在 数据 库 连 接 上 施加 
了 排 它 锁 ， 其 他 线程 在 等 待 锁 释放 的 过 程 中 超时 了 。 


















































Python 的 SQLite 包装 程序 为 线程 等 竺 锁 释放 设 定 了 默认 的 超时 时 间 ， 超 过 这 个 值 就 抽出 operattonatError: 
database is Locked 错误 。 








这 个 错误 可 以 采用 下 述 方法 解决 : 






































。 换 用 其 他 数据 库 后 端 。 在 特定 的 时 刻 ，SQLite 对 真实 的 应 用 程序 来 说 太 过 轻 量 了 ;并 发 错误 就 表明 到 
了 这 样 的 时 刻 。 


。 重 写 代 码 ， 减 少 并 发 ， 并 且 确 保 数据 库 事务 历时 较 短 。 
。 在 数据 库 选项 中 设 定 timeout， 设 为 较 大 的 超时 时 间 




































































'OPTIONS' :{ 
和 
'timeout': 20， 
本 

}, 


这 样 只 是 等 待 时 间 变 长 了 ， 对 锁定 错误 本 身 没有 采取 任何 解决 措施 。 


21.4.5 不 支持 QuerySet.seLect_for_update() 








SQLite 不 支持 SELECT .. FOR UPDATE 名 法。 即便 调用 也 没 任何 效果 。 


21.4.6 原始 查询 不 支持 Python 那 种 指定 参数 的 格式 











多 数 后 端的 原始 查询 〈Manager.raw() 或 cursor.execute()) 可 以 使 用 Python 那 种 指定 参数 的 格式 ， 即 在 查 
询 中 以 '%(name)s' 形式 指定 占 位 符 ， 然 后 通过 字典 (而 非 列 表 ) 传人 参数 。SQLite 不 支持 这 种 方式 。 




















21.4.7 connection.queries 中 放 在 引号 里 的 参数 








如 果 把 参数 放 在 引号 中 代 换 ，sqLite3 无 法 获取 SQL。connection.queries 输出 的 SQL 是 通过 字符 串 插 值 重 
新 构建 的 ， 可 能 不 准确 。 把 查询 复制 到 SQLite shell 之 前 一 定 要 添加 必要 的 引号 。 




















21.5 Oracle 说 明 


Django 支持 Oracle Database Server 11.1 及 以 上 版 本 。cx_0racle Python 驱动 要 使 用 4.3.1 或 以 上 版 本 ， 不 过 推 
荐 使 用 5.1.3 或 以 上 版 本 ， 因 为 这 些 版 本 支持 Python 3。 
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意 sy 


， 因 此 如 果 想 使 用 较 新 的 版 本 ， 使 
编译 cx_0racte 5.0.1 或 以 上 版 本 时 可 





制 。 


为 了 让 python manage.py migrate 


为 了 运行 项 目 


\ 芝 
EY 
,区 、， 


权限 ， 


试 。 














有 些 测试 组 件 还 要 创建 视图 ， 为 此 ， 


cx_0racte 5.0 有 个 缺陷 ， 会 损 





























CREATE TABLE 
CREATE SEQUENCE 
CREATE PROCEDURE 


CREATE TRIGGER 


坏 Unicode， 
j 5.0.1 版 吧 。 


以 选择 设 定 WITH_UNICODE 环境 变 





因此 不 要 在 Django 中 使 用 。 














cx_Oracle 5.0.1 修正 了 这 个 问 











量 。 推 荐 设 定 


这 个 环境 变量 明 


， 但 不 强 


























让 
中 





的 测试 组 件 ， 数 据 库 用 户 通 








CREATE USER 

DROP USER 

CREATE TABLESPACE 

DROP TABLESPACE 

CREATE SESSION WITH ADMIN OPTION 
CREATE TABLE WITH ADMIN OPTION 


CREATE SEQUENCE WITH ADMIN OPTION 


还 需要 具有 下 述 额外 的 权限 : 


CREATE PROCEDURE WITH ADMIN OPTION 


CREATE TRIGGER WITH ADMIN OPTION 


虽然 RESOURCE 角 














而 且 具 有 RESOURCE WITH ADMIN OPTION 权限 的 用 户 可 以 把 RESOURCE 外 
能 把 单独 的 权限 (如 CREATE TABLE) 赋予 他 人 ， 











能 正常 使 用 ， 你 的 Oracle 数据 库 用 户 必 须 具 有 执行 下 述 操作 的 权限 : 


色 具 有 必须 的 CREATE TABLE、 CREATE SEQUENCE、 CREATE PROCEDURE 和 CREATE TRIGGER 






































组 件 就 是 如 此 。 


这 些 权限 DBA 角 


Oracle 数据 库 后 端 使 用 SYS .DBMS_LOB 包 ， 因 此 
晶 也 有 例外 ， 如 果 没 有 这 个 权限 ， 


限 ， 1 




















色 都 








j 户 还 要 


只 有。 在 开发 者 个 人 私 























的 数据 库 中 适合 使 用 这 个 角色 。 























用 户 要 有 在 其 上 执行 操作 的 权限 。 























要 像 下 面 这 样 赋予 





GRANT EXECUTE ON SYS.DBMS_LOB TO user; 


21.5. 


1 连接 数据 库 


色 赋 予 他 人 ， 但 是 
因此 RESOURCE NITH ADMIN OPTION 权限 通常 还 不 足以 运 和 


具有 CREATE VIEW WITH ADMIN OPTION 权限 。Django 


是 这 样 的 用 户 不 
二 测 


vp i 


























自己 的 测试 














通常 ， 所 有 用 





户 都 有 这 个 权 











如 果 使 用 Oracle 数据 库 的 服务 名 连接 数据 库 ， 在 settings.py 文件 中 要 像 下 面 这样 设 置 : 








DATABASES = { 


'default': { 
'ENGINE': 'django.db.backend 
'NAME': 'xe', 
'USER': 'a_user', 


s.oracle', 
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"PASSWORD ' : 'a_password ' ， 
“HOST 
"PORT' : '', 


} 


此 时 ，HOST 和 PORT 应 该 留 空 。 然 而 ， 如 果 不 使 用 tnsnames .ora 文件 或 类 似 的 命名 方法 ， 而 想 使 用 SID (下 




















例 中 的 xe) 连接 数据 库 ， 要 像 下 面 这 样 设 定 HOST 和 PORT: 











DATABASES = { 


'default': { 
'ENGINE': 'django.db.backends.oracle', 
'NAME': 'xe', 


'USER': 'a_user', 

'PASSWORD': 'a_password', 

'HOST': 'dbprodO1ned.mycompany .com ' ， 
"PORT' : '1540 ' ， 


} 


HOST 和 PORT 要 么 留 空 ， 要 么 都 设 定 。Django 会 根据 这 两 个 选项 的 设 定 情况 选择 不 同 的 连接 描述 符 (descrip- 


tor) 。 


21.5.2 threaded 选项 











如 果 计划 在 多 线程 环境 中 运行 Django (例如 在 现代 的 操作 系统 中 使 用 默认 的 MPM 模块 运行 Apache) ， 必 须 





在 Oracle 数据 库 的 配置 中 把 threaded 选项 设 为 True: 








'OPTIONS': { 
'threaded': True, 


}; 


如 若 不 然 ， 可 能 导致 裔 省 和 其 他 怪异 的 行为 。 





21.5.3 INSERT . RETURNING INTO 


Oracle 后 端 插入 新 行 时 ， 默 认 使 用 RETURNING INT0 子 句 高 效 获取 AutoField 的 值 。 在 某 些 特别 的 情况 下 ， 这 














种 行为 可 能 导致 natabaseError， 例 如 插 和 人 远程 表 ， 或 者 插入 设 定 了 INSTEAD OF 触发 器 的 视图 。 


若 想 禁用 RETURNING INT0 子 句 ， 在 数据 库 配 置 中 把 use_returning_into 选项 设 为 False: 





'OPTIONS': { 
"use_returning_into' : False, 


}, 
此 时 ，Oracle 后 端 将 使 用 单独 的 一 个 SELECT 查询 获取 AutoField 的 值 。 























21.5.4 命名 问题 


Oracle 限制 名 称 的 最 大 长 度 为 30 个 字符 。 





鉴于 此 ， 后 端 会 截断 数据 库 标 识 符 ， 把 截断 后 的 名 称 的 后 四 个 字符 换 成 可 复 现 的 MD5 哈 希 值 。 此 外 ， 后 端 





会 把 数据 库 标 识 符 变 成 全 大 写 。 
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为 了 防止 这 些 转换 (通常 只 在 处 理 








日 数据 库 或 访问 别人 的 表 时 才 有 这 样 的 要 求 ) ， 把 名 称 放 在 引号 里 : 














class LegacyModel(models.Model): 
class Meta: 
db_table = '"name _ left _ in lowercase"’ 


class ForeignModel(models.Model): 
class Meta: 
db_table = '"OTHER_USER"."NAME ONLY_SEEMS OVER_ 30"" 


放 在 引号 中 的 名 称 可 以 在 Django 支持 的 其 他 数据 库 后 端 中 使 用 ， 但 唯 独 Oracle 不 支持 。 


如 果 使 用 Oracle 的 关键 字 命 名 模型 字段 或 者 作为 db_column 选项 的 值 ， 运 行 migrate 命令 时 可 能 会 遇 到 
0ORA-06552 错误 。Django 把 查询 中 用 到 的 所 有 标识 符 都 放 在 引号 里 ， 这 样 在 多 数 情 况 下 能 避免 这 种 问题 ， 但 
是 用 Oracle 的 数据 类 型 命名 列 时 依然 可 能 会 遇 到 这 个 错误 。 因 此 ， 尤 其 要 小 心 ， 别 把 字段 命名 为 date、 


timestamp、number 或 float。 

































































21.5.5 NULL 和 空 字 符 串 


Django 一 般 倾 向 于 使 用 空 字 符 串 〈'' ) ， 而 不 是 NULL， 但 是 在 Oracle 看 来 ， 二 者 是 等 价 的。 为 了 解决 这 个 问 
题 ，Oracle 后 端 忽略 允许 使 用 空 字符 串 的 字段 上 设 定 的 nutl 选项 ， 按 照 null=True 生成 DDL。 从 数据 库 中 读 
取 数 据 时 ，Oracle 后 端 假定 这 样 的 字段 中 存储 的 NULL 值 其 实 是 表示 空 字符 串 ， 并 且 据 此 悄 无 声息 地 转换 数 
据 。 















































21.5.6 对 TextField 的 限制 











Oracle 后 端 把 TextField 存储 为 NCLOB 类 型 。 此 时 ，Oracle 会 对 LOB 类 型 的 列 做 出 一 些 限制 ; 


。 LOB 列 不 可 以 用 作 主 键 。 
。 LOB 列 不 能 建立 索引 。 


。 LOB 列 不 能 使 用 SELECT DISTINCT 查询 。 这 意味 着 ， 使 用 Oracle 时 ， 在 包含 TextField 字段 的 模型 上 
调用 QuerySet .distinct 会 出 错 。 解 决 方法 是 ， 结 合 QuerySet.defer 和 distinct() 方法 ， 把 TextField 
字段 排除 在 SELECT DISTINCT 得 到 的 列表 之 外 。 









































21.6 使 用 第 三 方 数 据 库 后 端 


除了 官方 支持 的 数据 库 之 外 ， 还 有 些 第 三 方 后 端 ， 让 你 能 在 Django 中 使 用 其 他 数据 库 : 























。 SAP SQL Anywhere 
。 IBM DB2 

。 Microsoft SQL Server 
。 Firebird 

。 ODBC 

。 ADSDB 




















这 些 非 官方 后 端 支持 的 Django 版 本 和 ORM 功能 差异 巨大 。 关 于 这 些 非 官方 后 端 具体 支持 的 功能 和 查询 类 
型 ， 请 通过 各 项 目的 支持 渠道 询问 。 
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21.7 集成 旧 数据 库 
































虽然 Django 最 适合 用 来 开发 新 应 用 程序 ， 但 是 也 不 是 不 能 集成 旧 数 据 库 。Django 自 带 了 很 多 实用 工具 ， 力 
求 简化 这 一 过 程 。 


安装 好 Django 之 后 ， 可 以 按照 下 述 一 般 过 程 集成 现 有 数据 库 。 











21.7.1 配置 数据 库 参 数 





你 要 告诉 Django 数据 库 连接 参数 和 数据 库 名 。 在 DATABASES 设置 中 为 'default' 连接 的 下 述 各 个 键 设 值 : 








。 NAME 

。 ENGINE <DATABASE-ENGINE> 
。 USER 

。 PASSWORD 

。 HOST 


。 PORT 


21.7.2 自动 生成 模型 























Django 自 带 的 inspectdb 实用 工具 可 以 通过 内 省 现 有 数据 库 创建 模型 。 运 行 下 述 命令 可 以 看 到 相关 输出 : 





















































python manage.py inspectdb 

















使 用 标准 的 Unix 输出 重 定 向 把 输出 的 内 容 保存 到 一 个 文件 中 (在 Windows 中 也 可 以 使 用 ) : 

















python manage.py inspectdb > models.py 





























这 个 工具 的 目的 只 是 为 了 节省 时 间 ， 不 能 作为 生成 模型 的 最 终结 果 。 详 情 参 见 inspectdb 的 文档 。 


整理 好 模型 之 后 ， 把 文件 命名 为 modeLts.py， 保 存 到 应 用 所 在 的 Python 包 里 。 然 后 把 应 用 添加 到 IN- 
STALLED_APPS 设置 中 。 




















inspectdb 默认 创建 不 用 管理 的 模型 。 即 在 模型 的 Meta 类 中 设 有 managed = False， 不 让 Django 负责 创建 、 
修改 和 删除 表 。 














class Person(models.Model): 
id = models.IntegerField(primary_key=True) 
first_name = models.CharField(max_length=70) 
class Meta: 
managed = False 
db_table = 'CENSUS_PERSONS' 








如 果 想 让 Django 管理 表 的 生命 周期 ， 要 把 managed 选项 的 值 改 为 True (或 者 干脆 删除 ， 因 为 True 是 默认 
值 ) oo 





21.7.3 安装 Django 的 核心 表 





接 下 来 ， 运 行 mtgrate 命令 ， 安 装 其 他 所 需 的 数据 库 记录 ， 例 如 管理 权限 和 内 容 类 型 


python manage.py migrate 
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21.7.4 清理 生成 的 模型 





正如 你 想 ， 数 据 库 内 省 不 完美 ， 得 到 的 模型 代码 要 适当 做 些 清理 。 下 面 给 出 几 点 提示 : 





























。 每 个 数据 库 表 转换 成 一 个 模型 类 ( 即 数据 库 表 与 模型 类 之 间 是 一 对 一 关系 ) 。 因 此 ， 要 重 构 多 对 多 联 
结 表 的 模型 ， 改 成 ManyToManyField 对 象 。 

。 生成 的 各 个 模型 中 包含 每 一 个 字段 ， 包 括 DD 主键 字段 。 然 而 ，Django 在 没有 ID 主键 的 情况 下 会 自动 
添加 。 因 此 ， 要 把 类 似 这 样 的 代码 删除 : 



































id = models.IntegerField(primary_key=True) 











之 所 以 删除 ， 不 仅 是 因为 多 余 ， 如 果 要 在 表 中 添加 新 记录 ， 存 在 这 个 字段 还 可 能 导致 问题 。 

。 字段 的 类 型 (如 charField、DateField) 通过 数据 库 列 的 类 型 (如 VARCHAR、DATE) 确定 。 如 果 in- 
spectdb 无 法 判断 ， 将 使 用 TextFieLd， 并 在 生成 的 字段 代码 旁 插入 一 个 注释 : 'This field type is a 
guess.' (这 个 字段 的 类 型 是 猜 的 ) 。 留 意 这 样 的 注释 ， 如 有 必要 ， 相 应 地 修改 字段 类 型 。 

。 如 果 数 据 库 中 的 列 在 Django 中 没有 适当 的 字段 对 应 ， 可 以 放心 将 其 忽略 。Django 模型 层 无 需 包 含 表 
中 的 每 个 列 。 

。 如 果 数 据 库 列 的 名 称 是 Python 保留 字 (如 pass、class、for) ，inspectdb 将 在 属性 名 后 添加 
"_field"， 并 把 db_column 参数 设 为 真正 的 字段 名 (如 pass、class、for) 。 假 如 有 个 名 为 for 的 INT 
类 型 列 ， 生 成 的 模型 会 像 下 面 这 样 定义 : 









































































































































for_field = models.IntegerField(db_column='for') 


inspectdb 会 在 这 样 的 字段 旁 插 入 一 个 注释 : 'Field renamed because it was a Python reserved 
word.' (字段 重 命名 了 ， 因 为 它 是 Python 保留 字 ) 。 


。 如 果 数 据 库 中 有 引用 其 他 表 的 表 (多 数 数据 库 都 有 ) ， 可 能 要 调整 生成 的 模型 顺序 ， 以 正确 的 顺序 排 
列 引 用 其 他 模型 的 模型 。 假 如 Book 模型 有 个 外 键 引用 Author 模型 ， 那 么 Author 模型 就 要 在 Book 模型 
前 面 定 义 。 如 果 要 建立 关联 的 模型 尚未 定义 ， 可 以 用 字符 串 表 示 模 型 的 名 称 ， 不 能 直接 使 用 模型 对 
象 。 

。 inspectdb 能 检测 出 PostgreSQL、MySQL 和 SQLite 的 主键 ， 即 能 适时 插入 primary_key=True。 其 他 数 
据 库 则 要 自己 动手 ， 至 少 在 模型 中 的 一 个 字段 上 设 定 primary_key=True， 因 为 这 是 Django 模型 的 要 

。 只 有 PostgreSQL 和 特定 类 型 的 MySQL 表 才能 检测 出 外 键 。 检 测 不 出 来 时 ， 外 键 以 IntegerFietLd 表 
示 ， 即 假定 外 键 是 INT 类 型 的 列 。 
































































































































21.7.5 测试 ， 微 调 














以 上 是 基本 步骤 ， 做 完 之 后 还 要 微调 Django 生成 的 模型 ， 直 到 符合 自己 的 要 求 。 试 着 通过 Django 数据 库 
API 访问 数据 、 在 Django 管理 后 台中 编辑 对 象 ， 然 后 相应 地 修改 模型 文件 。 












































21.8 接 下 来 





本 书 正文 到 此 结束 | 








希望 本 书 没有 让 你 失望 ， 读 完 之 后 能 有 所 获 益 。 虽 然 本 书 可 以 作为 Django 全 面 的 参考 手册 ， 但 是 没有 什么 能 
取代 动手 操作 。 代 码 敲 起 来 吧 ， 望 你 借助 Django 取得 一 番 成 就 ! 


余下 的 几 篇 附录 详解 Django 中 的 各 个 函数 和 字段 ， 仅 作 参 考 之 用 。 
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附录 A 模型 定义 参考 指南 























第 4 章 讲解 了 模型 定义 的 基础 知识 ， 为 后 文 黄 定 了 基础 。 然 而 ， 还 有 大 量 可 用 的 模型 选项 没有 涵盖 。 本 篇 附 
录 说 明 模型 定义 可 用 的 各 个 选项 。 


A.1 字段 











模型 最 重要 的 部 分 (也 是 模型 唯一 必须 的 部 分 ) 是 所 定义 的 数据 库 字 段 。 


A.1.1 对 字段 名 称 的 限制 


Django 对 模型 字段 的 名 称 做 了 两 个 限制 : 





1. 字段 名 称 不 能 是 Python 保留 守 ， 否 则 会 导致 Python 句法 出 错 。 例 如 : 


class Example(models.Model): 
pass = models.IntegerField() #“pass” 是 保留 字 | 


2.， 字段 名 称 不 能 包含 多 个 连续 的 下 划 线 ， 否 则 会 影响 Django 的 查询 查找 句法 。 例 如 : 


class Example(models.Model): 
# “foo bar” 中 有 两 个 下 划 线 | 
foo_bar = models.IntegerField() 




















模型 中 的 各 个 字段 应 该 是 适当 Field 类 的 实例 。Django 通过 字段 所 属 的 类 确定 以 下 几 件 事 : 




















。 数据 库 列 的 类 型 (如 INTEGER、VARCHAR) 。 
。 在 Django 的 表单 和 管理 后 台中 使 用 的 小 组 件 (widget) (如 <input type="text">、<select>) 。 
。 必要 的 验证 ， 供 Django 的 管理 界面 和 表单 使 用 。 

































































每 个 字段 类 都 接受 一 组 选项 参数 。 例 如 ， 第 4 章 中 的 book 模型 是 这 样 定 义 num_pages 字段 的 : 
num_pages = models.IntegerField(blank=True, null=True) 


这 里 ， 为 字段 类 设置 了 blank 和 null 选项 。Django 中 可 用 的 各 个 字段 选项 参见 表 A-2。 














此 外 ， 有 些 类 还 定义 了 专门 的 选项 。 例 如 ，CharField 有 个 必须 的 选项 nax_Length， 其 默认 值 为 None， 如 下 
所 示 : 


title = models.CharField(max_length=100) 


这 里 ， 我 们 把 max_length 字段 选项 设 为 100， 限 制 书 名 的 长 度 不 能 超过 100 个 字符 。 








表 A-1 按 字 母 顺序 列 出 了 所 有 字段 类 。 
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表 A-1，Django 模型 字段 类 




































































































































































































































































字段 类 默认 小 组 件 说 明 
AutoField N/A 根据 ID 自动 递增 的 IntegerField。 
， 64 位 整数 ， 与 IntegerField 很 像 ， 但 取 值 范围 是 
BigIntegerField NumberInput 
-9223372036854775808 到 9223372036854775807。 
， 存储 原始 二 进 制 数据 的 字段 。 只 支持 bytes 类 
BinaryField N/A OE 人 汪汪 的 全 人 
型 。 注 意 ， 这 个 字段 的 功能 有 限 。 
2 役 。 尼 想 接受 null 值 ， 
BooleanField CheckboxInput 假 值 字段 。 如 果 想 接受 nutt 值 ， 使 用 
NullBooleanField, 
字符 串 字段 ， 针 对 长 度 较 小 的 字符 串 。 大 量 文本 
CharField TextInput 应 该 使 用 TextFieLd。 有 个 额外 的 必须 参数 ; 
max_Length， 即 字段 的 最 大 长 度 (字符 个 数 ) 。 
日 期 ， 在 Python 中 使 用 datetime.date 实例 表 
示 。 有 两 个 额外 的 可 选 参数 : auto_now， 每 次 保 
DateField DateInput a yy 
存 对 和 象 时 自动 设 为 当前 日 期 ，auto_now_add， 创建 
对 象 时 自动 设 为 当前 日 期 。 
日 期 和 时 间 ， 在 Python 中 使 用 datetime.datetime 
DateTimeField DateTimeInput pa ， EE “ , 
实例 表示 。 与 DateField 具有 相同 的 额外 参数 。 
固定 精度 的 小 数 ， 在 Python 中 使 用 Decimal 实例 
DecimalField TextInput 表示 。 有 两 个 必须 的 参数 : max_digits 和 
decimaL_pLaces。 
诸 时 间 跨 度 ， Pyth timedelt 
DurationField TextInput 存储 时 间 跨 度 tnot ee ein 
不 。 
一 种 CharField， EmailValidator 验证 输入 。 
EmailField TextInput Chacr le 使 mattvatidator 验证 输入 
max_Length 的 默认 值 为 254。 
FileField ClearableFileInput ”文件 上 传 字段 。 详 情 参 见 下 一 节 。 
一 种 CharField， 限 定 只 能 系统 中 的 特定 
i ealeet 和 ield， 限 定 只 能 在 文件 系统 中 的 特定 目 
录 里 选择 文件 。 
浮 点 数 ， 在 Python 中 使 用 float 实例 表示 。 注 
FloatField NumberInput 意 ，fieLd.LocalLize 的 值 为 False 时 ， 默 认 的 小 组 
件 是 TextInput。 
所 有 属性 和 方法 都 继承 自 FileField， 此 外 验证 上 
ImageField ClearableFileInput ” 传 的 对 象 是 不 是 有 效 的 图 像 。 增 加 了 height 和 
width 两 个 属性 。 需 要 Pillow 库 支 持 。 
IntegerField NumberInput 整数 。 取 值 范围 是 -2147483648 到 2147483647， 在 
i . pi 
Django 支持 的 所 有 数据 库 中 可 放心 使 用 。 
IPv4 或 IPv6 地 址 ， 字 符 串 形式 192.0.2.30 
GenericIPAddressField TextInput "4 或 下 v6 地 址 ， 字 符 串 形式 (如 


2a02:42fe::4) 。 
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( 续 ) 















































































































































字段 类 默认 小 组 件 说 明 
类 似 于 BooLeanFieLd， NULL 可 作为 其 中 一 个 
NullBooleanField NullBooleanSelect 类 似 Rs 但 是 作为 其 中 
选项 。 
RS Nr 整数 。 取 值 范围 是 9 到 2147483647， 在 Django 文 
ositiveIntegerFie umberInpu 同 二 
持 的 所 有 数据 库 中 可 放心 使 用 。 
别名 (slug) 是 报 业 术语 ， 是 某 个 事物 的 简短 标 
SlugField TextInput Ne ep ed A 
注 ， 只 包含 字母 、 数 字 、 下 划 线 或 连 字符 。 
类 似 于 IntegerFieLd， 但 是 对 值 有 限制 。 取 值 范 
SmallIntegerField NumberInput 和 是 -32768 到 32767， 在 Django 支持 的 所 有 数据 
库 中 可 放心 使 用 。 
大 段 文本 字段 。 如 果 指 定 了 max_tength 选项 ， 这 
TextField Textarea 是 本 7 
一 限制 在 自动 生成 的 表单 字段 中 会 体现 出 来 。 
才 间 ， Python 中 datetime .time 实 从 
TimeField TextInput 出 加 人 
/小 oo 
全 入 URL 的 CharFieLd。 可 选 Length 选 
URLField URLInput ] 于 输入 eharnte lds We valength 
项 。 
诸 通 一 标识 码 。 Pyth 4] UUID 
0 rn 用 于 存储 通用 唯 标识 码 。 使 用 Python 的 








A.1.2 FileField 说 明 


不 支持 primary_key 和 unique 选项 ， 否 则 会 抛 H 


有 两 个 可 选 的 参数 : 


1. FilerField.upload_ to 


2. FileField.storage 


FileField.upload to 





追加 到 MEDIA_RooT 设置 后 面 的 本 地 文 伯 
串 ， 上 传 文件 时 将 替换 成 当时 的 日 其 





























调用 后 返回 上 传 的 路 径 (包括 文件 名 ) 。 











用 正和 斜 线 ) ， 传 给 存储 系统 。 接 受 的 两 个 参数 是 : 





HTypeError 。 


系统 路 径 ， 用 于 构建 url 属性 的 值 。 可 以 包含 strftime() 格式 化 字符 
/时 间 (以 防 上 传 的 文件 填 满目 录 ) 。 还 可 以 是 可 调用 的 对 象 ， 如 函数 ， 
这 个 可 调用 对 象 必须 接受 两 个 参数 ， 而 且 返 回 Unix 风格 的 路 径 (使 











。 实例 。FileField 所 在 模型 的 实例 。 严 格 来 说 ， 是 所 上 传 文件 依附 的 实例 。 多 数 情况 下 ， 这 个 对 象 沿 
未 存 信 数据库， 所 以 如 果 主 键 使 用 默认 的 AutoFieLd， 主 键 字段 可 能 还 没有 值 。 


。 文件 名 。 文 件 原来 的 名 称 。 最 终 得 到 的 路 径 可 能 采用 、 也 可 能 不 采用 这 个 文件 名 。 











FileField.storage 


存储 器 对 象 ， 处 理 文件 的 存 取 。 这 个 字段 默认 的 表 六 


















































和 小 组 件 是 ClearableFileInput。 在 模型 中 使 用 FileField 








或 ImageField (参见 后 文 ) 要 按照 下 述 步 又 来 做 : 














附录 A 模型 定义 参考 指南 - 323 





。 在 设置 文件 中 把 MEDIA_ROOT 设 为 Django 存储 上 传 文件 的 目录 的 完整 路 径 。 











(出 于 性 能 上 的 考虑 ， 上 


传 的 文件 不 存储 在 数据 库 中 。) 把 MEDIA_URL 设 为 那个 目录 的 公开 URL。 运 行 Web 服务 器 的 用 户 账户 
必须 有 那个 目录 的 写 权 限 。 


。 在 模型 中 添加 FileField 或 ImageField， 把 upload_to 选项 设 为 MEDIA_ROOT 中 的 一 个 子 目录 ， 用 于 存 








储 上 传 的 文件 。 
。 存储 在 数据 库 














的 绝对 路 径 。 








上 传 文件 时 一 定 要 谨慎 处 理 文件 的 类 型 ， 以 防 出 现 安全 
要 求 。 倘 若 毫 无 防备 ， 允 许 把 文件 上 传 到 Web 服务 器 文档 根 目录 中 的 某 个 目 











的 只 是 文件 的 路 径 (相对 于 MEDIA_R00T) 。 多 数 时 候 只 需 使 
性 。 例 如 ， 如 果 ImageField 名 为 mug_shot， 在 模板 




















是 洞 。 上 传 的 所 有 文 









































牛 都 要 验证 ， 而 


























| 录 中 ， 而 不 验证 ， 不 


就 可 能 上 传 CGI 或 PHP 脚本 ， 然 后 访问 网 站 的 某 个 URL 执行 脚本 。 可 别 犯 傻 ! 
还 要 注意 ， 即 便 上 传 的 是 HTML 文件 也 可 能 造成 安全 威胁 ， 因 为 HTML 文件 会 由 浏览 器 执行 〈 而 非 服务 





器 ) ， 从 而 导致 XSS 或 CSRF 攻击 。 在 数据 库 9 








介 室 和 链 





与 





个 子 付 。 


FileField 和 FieldFile 











其 他 字段 一 样 ， 可 以 通过 max_length 选项 修改 最 大 长 度 。 





在 模型 上 访问 FileField 时 ， 是 以 FieldFile 实例 为 代理 访问 底层 文件 的 。 除 了 继承 自 djan- 
go.core.files.File 的 功能 之 外 ， 这 个 类 还 有 几 个 属性 和 方法 ， 可 与 文件 数据 交互 。 


FieldFile.url 


























只 读 特 性 (property) ， 调 用 底层 Storage 类 的 urtL() 方法 获取 文件 的 相对 URL。 


FieldFile.open(mode='rb') 


行为 与 Python 标准 的 open() 方法 类 似 ， 以 mode 指定 的 模式 打开 模型 中 与 这 个 





FieldFile.close() 








实例 关联 的 文件 。 





行为 与 Python 标准 的 file.close() 方法 类 似 ， 关 闭 与 这 个 实例 关联 的 文件 。 





FieldFile.save(name, content, save=True) 








Django 提供 的 url 属 
PP 可 以 使 用 {{ object.mug_shot.url }} 获取 图 像 


保 文件 类 型 符合 




















不 好 意 的 人 


FP，FileField 实例 对 应 的 是 varchar 列 ， 最 大 长 度 默 认为 100 





这 个 方法 把 传人 的 文件 名 和 文件 内 容 传 给 字段 的 存储 类 ， 然 后 把 存储 的 文件 与 模型 字段 关联 起 来 。 如 果 想 自 


己 动 手 把 文 件数 据 与 模型 9 








FP 的 FileField 实例 关联 起 来 ， 使 用 save() 方法 持 


久 存 储 文件 数据 。 





这 个 方法 有 两 个 必须 的 参数 ，nane 是 文件 的 名 称 ，content 是 包含 文件 内 容 的 对 象 。 可 选 的 save 参数 控制 改 
动 与 字段 关联 的 文件 后 是 否 保存 模型 实例 。 默 认为 True。 





注意 ，content 参数 的 值 应 该 是 django.core.files.File 实例 ， 而 非 Python 内 置 的 文件 对 象 。 可 以 像 下 镍 
样 使 用 现 有 的 Python 文件 对 象 构建 File 实例 : 











from django.core.files import File 
# 使 用 Python 内 置 的 open() 打开 现 有 文件 
f = open('/tmp/hello.world') 


myfile = File(f) 


也 可 以 像 这 样 使 用 Python 字符 串 构建 : 




















区 
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from django.core.files.base import ContentFile 
myfile = ContentFile("hello world") 


FieldFile.delete(save=True) 


删除 与 这 个 实例 关联 的 文件 ， 并 且 清 除 字段 上 的 所 有 属性 。 如 果 调用 delete() 时 文件 是 打 玫 


闭 。 














可 选 的 save 参数 控制 删除 与 字段 关联 的 文件 后 是 否 保存 模型 实例 。 默 认为 True。 


注意 ， 删 除 模型 后 ， 相 关 的 文件 不 会 删除 。 如 果 
自 定 义 的 管理 命 人 











务 定期 运行 一 个 

















A.2 通用 字段 选项 


表 A-2 列 出 Django 中 所 有 可 选 的 字段 选项 。 这 些 选项 可 以 在 人 有 








表 A-2，Django 通用 字段 选项 


相 


4 





) 。 





清理 无 主 文件 ， 只 能 














F 何 字段 类 型 中 使 用 。 








F 的 ， 还 会 将 其 关 


己 动手 (例如 ， 手 动 或 通过 cron 任 





选项 


说 明 





null 


blank 


choices 


db_column 


db_index 


db_tablespace 


default 


editable 


设 为 True 时 ，Django 在 数据 库 





于 字符 串 的 字段 ， 如 CharField 和 TextField, 不 
串 ， 而 非 NULL。 对 基于 字符 下 


== 


字符 串 值 始终 存储 为 空 字符 


日 








把 空 值 存储 为 NULL。 默 认为 Fal 
应 该 使 用 null， 


























串 的 字段 来 说 ， 如 果 想 让 表单 
让 BooleanField 接受 nuLL 值 ， 








设 为 True 时 ， 字 段 允 许 空白 值 。 默 认为 False。 注 意 ， 这 与 null 不 同 。 
只 针对 数据 库 ， 而 blank 是 针对 数据 验证 的 。 





null 


可 迁 代 的 对 象 (如 列表 或 元 组 ) 


代 对 象 构成 (如 [(A，B)，(A，B) . 
定 这 个 选项 ， 默 认 的 表单 小 组 件 将 




















? 








1 两 个 元 组 ( 
]) 9 


包括 






















































































框 。 各 元 组 中 的 第 一 个 元 素 是 





自身 ) 组 成 的 可 和 迭 
于 设 定 字 段 的 选项 。 如 果 设 
1 标准 的 文本 字段 变 成 带 选 项 的 选择 


se。 基 
因为 空 


和 不 基于 字符 





接受 空 值 ， 还 要 设 定 blank=True。 如 果 想 
使 用 NuLLBooLeanFietLd。 





E 在 模型 上 设 定 的 值 ， 第 二 个 元 素 是 人 





LL 





类 可 读 的 名 称 。 


字段 使 用 的 数据 库 列 名 称 。 如 未 指定 ，Django 将 使 用 字段 的 名 称 。 
设 为 True 时 ， 在 字段 上 建立 数据 库 索 引 。 
为 有 索引 的 字段 指定 索引 使 用 的 数据 库 表 空间 (tablespace) 名 称 。 默 认 











为 项 目 





的 DEFAULT_INDEX_TABLESPACE 设置 ， 或 者 模型 的 db_tabLespace 属 





性 。 如 果 数 据 库 后 端 不 支持 为 索引 指定 表 空 间 ， 忽 略 这 个 选项 。 


字段 的 默认 值 。 可 以 是 一 个 值 ， 也 可 以 是 一 个 可 调用 对 象 。 为 后 者 时 ， 
每 次 新 建 对 象 都 会 调用 一 次 。 黑 认 值 不 能 是 可 变 的 (mutable) 对 象 ( 模 








EE 





型 实例 、 列 表 、 
实例 中 字段 的 默认 值 。 





设 为 False 时 ， 字 段 不 在 管理 后 台 或 其 他 ModeLForm 中 显示 。 验 订 


也 会 跳 过 。 默 认为 True。 




















琴 








等 等 ) ， 因 为 对 那个 对 象 的 引用 将 作为 所 有 新 模型 





F 模 型 时 
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选项 说 明 
用 于 覆盖 字段 抛 出 异常 时 的 默认 消息 。 值 为 一 个 字典 ， 通 过 键 指定 想 覆 
error_messages 善 的 错误 消息 。 错 误 消 息 键 包括 null、blank、invalid、 


invalid choice、unique 和 unique_for_date。 


在 表单 小 组 件 旁 显示 的 额外 帮助 文本 。 即 便 不 在 表单 中 显示 ， 也 能 用 作 
heLp_text 文档 。 注 意 ， 在 自动 生成 的 表单 中 ， 不 会 转 义 这 里 的 HIML， 因 此 ， 如 
果 需 要 ， 可 以 在 帮助 文本 中 使 用 HTML。 

设 为 True 时 ， 指 定 字 段 为 模型 的 主键 。 如 果 模 型 中 没有 一 个 字段 设 定 

primary_key=True，Django 会 自动 添加 一 个 AutoFieLd， 用 于 存储 主键 ， 
因此 ， 除 非 想 覆盖 默认 的 主键 行为 ， 否 则 无 需 在 任何 字段 上 设 定 
primary_key=True。 主 键 字 段 是 只 读 的 。 


设 为 True 时 ， 在 表 中 字段 的 值 必须 是 唯一 的 。 这 一 限制 由 数据 库 层 和 模 
unique 型 验证 实施 。 除 了 ManyToManyField、OneToOneField 和 FiLeFietLd 之 外 ， 
其 他 字段 都 可 以 设 定 这 个 选项 。 


设 为 DateField 或 DateTimeField 字段 的 名 称 ， 确 保 与 所 在 字段 的 组 合 是 
唯一 的 。 假 如 有 个 title 字段 设 定 了 unique_for_date="pub_date"， 那 么 
Django 不 允许 出 现 title 和 pub_date 都 相同 的 两 条 记录 。 这 个 限制 在 验 
证 模型 时 由 Model.validate_unique() 实施 ， 而 不 在 数据 库 层 实施 。 































































































primary_key 
























































unique_for_date 



































unique_for_month 类 似 于 unique_for_date， 不 过 验证 唯一 性 时 考虑 的 是 月 份 。 
unique_for_year 类 似 于 unique_for_date， 不 过 验证 唯一 性 时 考虑 的 是 年 份 。 











字段 的 人 类 可 读 名 称 。 如 果 未 设 定 ，Dijango 将 使 用 字段 的 属性 名 称 〈 下 
划 线 转换 成 空格 ) 自动 生成 一 个 。 


validators 用 于 验证 字段 的 验证 器 列表 。 





verbose_name 


























A.3 字段 属性 参考 指南 
































每 个 字段 实例 都 有 几 个 可 用 于 内 省 行为 的 属性 。 如 果 想 根据 字段 的 功能 编写 代码 ， 请 使 用 这 些 属性 ， 别 通过 
isinstance 检查 。 这 些 属 性 可 以 与 Model._meta API 结合 起 来 进一步 缩 窗 要 查找 的 字段 类 型 。 自 定义 的 模型 
字段 应 该 实现 下 述 旗 标 。 



























































A.3.1 字段 的 属性 


FieLd.auto_created 



































布尔 旗 标 ， 指 明 字段 是 否 为 自动 创建 的 。 模 型 继承 使 用 的 OneTo0neFietLd 就 是 自动 创建 的 。 

















Field.concrete 











布尔 旗 标 ， 指 明 字 段 是 否 关 联 数据 库 列 。 
Field.hidden 


布尔 旗 标 ， 指 明 一 个 字段 是 否 用 于 支持 另 一 个 非 隐藏 字段 的 功能 〈 例 如 组 成 GenericForeignkKey 的 con- 
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tent_type 和 object_id 字段 ) 。 这 个 旗 标 用 于 把 模型 中 公开 的 字段 子 集 从 全 体 字 段 中 区 分 出 来 。 

















Field.is_relation 


布尔 旗 标 ， 指 明 一 个 字段 是 否 包含 指向 另 一 个 或 多 个 模型 的 引用 (如 ForeignKey、ManyToManyField、One- 
To0neFieLd， 等 等 ) 。 





Field.model 











回 定义 字段 的 模型 。 如 果 字 段 在 模型 的 超 类 中 定义 ，modet 指 代 超 类 ， 而 不 是 所 在 模型 类 的 实例 。 








可 


A.3.2 包含 关系 的 字段 的 属性 


这 些 属 性 用 于 查询 关系 的 基数 和 其 他 细节 。 所 有 字段 都 有 这 些 属性 ， 然 而 仅 在 关系 类 型 的 字段 
(Field.is_relation=True) 上 有 意义 。 


















































FieLd.many_to_many 








布尔 旗 标 ， 字 段 有 多 对 多 关系 时 为 True， 和 否则 为 FaLse。 在 Django 中 ， 只 有 ManyToManyField 的 这 个 属性 值 
为 True。 

















Field.many_to_one 





布尔 旗 标 ， 字 段 有 多 对 一 关系 时 为 True， 否 则 为 False。 














FieLd.one_to_many 








布尔 旗 标 ， 字 段 有 一 对 多 关系 时 为 True (例如 GenericRelation 或 ForeignKkey 的 另 一 端 ) ， 否 则 为 False。 








FieLd.one_to_one 





布尔 旗 标 ， 字 段 有 一 对 一 关系 时 为 True (如 OneToOneField) ,否则 为 False。 











Field.related model 





指向 与 字段 关联 的 那个 模型 。 例 如 ForeignKey(Author) 中 的 Author。 如 果 字 上 段 是 通用 关系 (例如 Generic- 
ForeignKey 或 GenericRelation) ， 那 么 related_model 值 为 None。 


A.4 关系 








Django 还 定义 了 一 系列 表示 关系 的 字段 。 


A.4.1 ForeignKey 





多 对 一 关系 。 有 一 个 必须 的 位 置 参数 : 与 模型 关联 的 类 。 若 想 创 建 递归 关系 ， 即 一 个 对 象 与 自身 有 多 对 一 关 
系 ， 使 用 models.ForeignKey('self')。 
































如 果 想 与 尚未 定义 的 模型 建立 关系 ， 不 能 使 用 模型 对 象 ， 应 该 使 用 模型 的 名 称 : 











from django.db import models 
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class Car(models.Model): 
manufacturer = models.ForeignKey('Manufacturer') 
i 


class Manufacturer(models.Model): 
# ... 
pass 











若 想 引用 另 一 个 应 用 中 定义 的 模型 ， 可 以 通过 完整 的 应 用 标注 明确 指定 模型 。 假 如 上 述 Manufacturer 模型 在 
名 为 production 的 应 用 中 定义 ， 可 以 这 么 做 : 





class Car(models.Model): 
manufacturer = models.ForeignKey('production.Manufacturer') 





这 样 可 以 避免 循环 导入 依赖 。Foreignkey 上 自动 建立 数据 库 索 引 。 若 想 禁 用 ， 把 db_index 设 为 False。 


如 果 创 建 外 键 是 为 了 保持 一 致 性 ， 而 不 是 想 做 联结 查询 ， 或 者 是 想 以 别 的 方式 创建 索引 (例如 部 分 索引 或 多 
列 索引 ) ， 可 以 禁止 自动 创建 索引 ， 避 免 开 销 。 





























数据 库 表述 





Django 在 背后 会 为 字段 名 称 深 加 ”id" 后 组 ， 作 为 数据 库 列 的 名称。 在 上 述 示例 中 ，Car 模型 对 应 的 数据 表 
中 将 出 现 manufacturer_id 列 。 



































这 个 行为 可 以 通过 db_column 选项 改变 ， 然而， 除非 需要 自己 编写 SQL， 和 否则 不 应 该 直接 自 定 义 数据 库 列 
名 。 我 们 处 理 的 应 该 是 模型 对 象 的 字段 名 称 。 





























参数 











ForeignKey 接受 一 些 额外 的 参数 (全 为 可 选 的 ) ， 用 于 定义 关系 的 细节 。 











limit_choices_ to 





使 用 ModelForn 演 染 或 在 管理 后 台中 显示 时 限制 罗列 这 个 字段 的 条 件 (默认 为 查询 集中 的 所 有 对 象 ) 。 值 为 
个 字典 、 一 个 Q 对 象 ， 抑 或 返回 一 个 字典 或 Q@ 对 象 的 可 调用 对 象 。 例 如 : 


























staff_member = models.ForeignKey(User, limit choices to={'is_staff': True}) 





此 时 ，ModelForn 中 的 相应 字段 只 会 列 出 is_staff=True 的 User 对 象 。 这 对 Django 的 管理 后 台 可 能 有 用 。 结 
合 Python 的 datetime 模块 限制 选择 的 日 期 范围 时 可 以 使 用 可 调用 对 象 。 例 如 : 























def limit pub_date choices(): 
return {'pub_date__lte': datetime.date.utcnow()} 


limit_choices_ to = limit_ pub_date_choices 


如 果 limit_choices_to 的 值 是 或 者 返回 一 个 Q 对 象 (适用 于 复杂 的 查询 ) ， 仅 当 模型 的 ModelAdmin 子 类 的 
raw_id_fields 属性 列 出 字段 时 才 对 字段 在 管理 后 台中 的 选择 有 效果 。 








reLated_name 


用 于 获取 所 关联 对 象 的 名 称 ， 也 是 reLated_query_name (目标 模型 使 用 的 反 向 过 滤器 名 称 ) 的 默认 值 。 详 细 
说 明和 示例 参见 “ 反 向 ”一 节 。 注 意 ， 在 抽象 模型 上 定义 关系 时 必须 设 定 这 个 值 。 设 定 这 个 值 时 ， 有 些 特 殊 的 
句法 可 用 。 如 果 不 想 让 Django 创建 逆向 关系 ， 把 reLated_name 设 为 '+'， 或 者 以 '+' 结尾 。 例 如 ， 下 述 代 码 
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确保 User 模型 没有 逆向 关系 ; 


User = models.ForeignKey(User, related name='+') 


reLated_query_name 





目标 模型 使 用 的 反 向 过 滤器 名 称 。 如 果 设 定 了 reLated_nane， 默 认为 它 的 值 ， 否则， 默认 为 模型 的 名 称 。 


# 声明 ForeignKey 时 设 定 reLated_query_name 
class Tag(models.Model): 
article = models.ForeignKey(Article, related_ name="tags", 
related_query_name="tag") 
name = models.CharField(max_length=255) 


# 现在 反 向 过 滤器 的 名 称 就 是 它 
Article.objects.filter(tag__name="important") 


to_field 














所 关联 对 象 上 建立 关系 的 字段 。Django 默认 使 用 所 关联 对 象 的 主键 。 











db_constraint 





控制 是 否 在 数据 库 中 为 外 键 创建 约束 。 默 认为 True， 多 数 情况 下 这 正 是 所 需 的 行为 。 设 为 False 极 有 可 能 
坏 数 据 完整 性 。 尽 管 如 此 ， 有 些 时 候 还 是 需要 设 为 False: 








。 有 无 效 的 旧 数 据 
。 创建 数据 库 分 片 

















如 果 设 为 Fatse， 访 问 不 存在 的 关联 对 象 时 抛 出 DoesNotExist 异常 。 





on_delete 








外 键 引 用 的 对 象 被 删除 时 ，Django 默认 模拟 SQL 约束 ON DELETE CASCADE 的 行为 ， 把 包含 外 键 的 对 象 也 删 





除 。 设 定 on_delete 参数 可 以 覆盖 这 个 行为 。 假 设 外 键 字 段 接受 null 值 ， 在 关联 的 对 象 被 删除 时 想 把 外 键 设 








为 nutL， 可 以 这 么 做 ; 
User = models.ForeignKey(User, blank=True, null=True, on_delete=models.SET_NULL) 


on_delete 可 取 的 值 在 django.db.models 中 定义 : 











。 CASCADE: 层 释 删除 ， 默认 值 。 

。 PROTECT: 抛 出 ProtectedError (django.db.IntegrityError 的 子 类 ) ， 禁 止 删除 被 引用 的 对 象 。 
。 SET_NULL: 把 外 键 设 为 nutl; 仅 当 null 为 True 时 才能 这 么 做 。 

。 SET_DEFAULT， 把 外 键 设 为 默认 值 ， 必 须 为 外 键 设 定 默 认 值 。 


swappable 





控制 外 键 指向 可 交换 的 模型 时 迁移 框架 的 反应 。 设 为 True 时 (默认 值 ) ， 如 果 外 键 指向 的 模型 与 set- 
tings.AUTH_USER_MODEL (或 其 他 可 交换 的 模型 设置 ) 的 当前 值 匹 配 ， 迁 移 中 的 关系 引用 这 个 设置 ， 而 不 直接 
引用 模型 。 
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仅 当 确定 模型 应 该 始终 指向 换 入 的 模型 〈 例 如 专 为 自 定义 的 用 户 模型 设计 的 个 人 资料 模型 ) 时 才 应 该 覆盖 这 
个 参数 ， 设 为 False。 设 为 False 并 不 是 指 换 出 后 可 以 引用 可 交换 的 模型 ， 而 是 指 迁移 中 的 外 键 指向 你 指定 的 
模型 (比如 说 ， 尝 试 使 用 不 支持 的 User 模型 时 会 出 大 错 ) 。 如 有 述 疑 ， 别 去 改 它 ， 使 用 默认 的 True。 












































A.4.2 ManyToManyField 


多 对 多 关系 。 有 个 必须 的 位 置 参数 : 与 之 关联 的 类 (与 ForeignKey 的 那个 参数 作用 完全 一 样 ， 包 括 递归 关系 
和 惰性 关系 ) 。 可 以 通过 这 个 字段 的 RelatedManager 添加 、 删 除 或 创建 关联 的 对 象 。 




















数据 库 表述 


为 了 表示 多 对 多 关系 ，Django 在 背后 会 创建 一 个 中 间 联 结 表 。 联 结 表 的 名 称 默 认 使 用 多 对 多 字段 的 名 称 和 多 
对 多 字段 所 在 模型 对 应 的 表 的 名 称 合成 。 


有 些 数据 库 限 制 表 名 的 长 度 ， 此 时 表 名 会 被 截断 ， 后 加 一 个 唯一 的 哈 希 值 ， 构 成 64 个 字符 。 因 此 ， 你 可 能 会 
看 到 名 为 author_books_9cdf4 的 表 一 一 这 是 相当 正常 的 。 联 结 表 的 名 称 可 以 使 用 db_table 选项 设 定 。 












































参数 
ManyToManyField 接受 一 些 额 外 的 参数 (全 为 可 选 的) ， 用 于 控制 关系 的 功能 。 





reLated_name 


同 ForeignKey.related_name。 


reLated_query_name 


同 ForetgnKey.reLated_query_name。 


limit_choices_to 





同 ForeignKey.limit_choices_to。 如 果 通 过 through 参数 自 定 义 了 中 间 联 结 表 ，ManyToManyField 的 Lim- 
it_choices_to 参数 没有 作用 。 














symmetrical 


仅 当 与 自身 建立 多 对 多 关系 时 有 用 。 以 下 述 代码 为 例 : 





from django.db import models 


class Person(models.Model): 
friends = models.ManyToManyField("self") 


Django 处 理 这 个 模型 时 ， 发 现 与 自身 建立 了 多 对 多 关系 ， 因 此 不 会 为 Person 类 添加 person_set 属性 ， 而 是 
假定 这 是 对 称 的 多 对 多 关系 ， 即 如 果 我 是 你 的 朋友 ， 你 就 是 我 的 朋友 。 


如 果 不 想 与 自身 建立 对 称 的 多 对 多 关系 ， 把 symmetrical 设 为 False。 这 样 ，Django 会 为 反 向 关系 添加 描述 
符 ， 把 多 对 多 关系 变 成 不 对 称 的 。 

















through 





Django 会 自动 生成 一 个 表 ， 用 于 管理 多 对 多 关系 。 然 而 ， 如 果 想 自 定义 中 间 表 ， 可 以 通过 through 选项 指定 
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表示 中 间 表 的 Django 模型 。 











需要 在 多 对 多 关系 中 增添 额外 数据 时 经 常 这 样 做 。 即 便 不 明确 设 定 through， 仍 然 有 个 隐 含 的 模型 类 ， 通 过 
它 可 以 直接 访问 管理 关系 的 表 。 这 个 隐 含 的 模型 有 三 个 字段 : 


























。 id: 关系 的 主键 。 


。 <containing_model>_id: 声明 ManyToManyField 那个 模型 的 id。 





。 <other_modeL>_ id: ManyToManyField 指向 的 那个 模型 的 id。 
这 个 模型 可 以 像 常规 的 模型 那样 使 用 ， 用 于 查询 关联 的 记录 。 


throughfields 

















仅 当 自 定义 了 中 间 模 型 时 有 用 。Django 通常 能 自行 判断 使 用 哪些 字段 建立 多 对 多 关系 。 

















db_table 








存储 多 对 多 数据 的 表 名 。 如 果 不 设 定 ，Django 会 基于 定义 关系 的 模型 对 应 的 表 名 和 字段 的 表 名 生成 一 个 。 





db_constraint 














控制 是 否 在 数据 库 中 的 中 间 表 上 为 外 键 创建 约束 。 默 认为 True， 多 数 情况 下 这 正 是 所 需 的 行为 ， 设 为 False 
极 有 可 能 破坏 数据 完整 性 。 


尽管 如 此 ， 有 些 时 候 还 是 需要 设 为 False: 

















。 有 无 效 的 旧 数 据 
。 创建 数据 库 分 片 











不 能 同时 设 定 db_constraint 和 through。 


swappable 


控制 多 对 多 字段 指向 可 交换 的 模型 时 迁移 框架 的 反应 。 设 为 True 时 (默认 值 ) ， 如 果 多 对 多 字段 指向 的 模型 
与 settings.AUTH_USER_MODEL (或 其 他 可 交换 的 模型 设置 ) 的 当前 值 匹 配 ， 迁 移 中 的 关系 引用 这 个 设置 ， 而 
不 直接 引用 模型 。 
















































































仅 当 确定 模型 应 该 始终 指向 换 入 的 模型 〈 例 如 专 为 自 定义 的 用 户 模 型 设计 的 个 人 资料 模型 ) 时 才 应 该 覆盖 这 
个 参数 ， 设 为 False。 如 有 迟疑 ， 别 去 改 它 ， 使 用 默认 的 True。 多 对 多 字段 不 支持 validators。null 没有 效 
果 ， 因 为 这 样 在 数据 库 层 无 法 引用 关系 。 
































A.4.3 OneToOneField 





一 对 一 关系 。 理 论 上 ， 这 与 设 定 了 unique=True 的 外 键 字段 一 样 ， 但 是 关系 的 另 一 端 只 返回 一 个 对 象 。 一 个 
模型 的 主键 以 某 种 方式 扩展 另 一 个 模型 时 最 常 建立 这 种 关系 。 多 表 继 承 的 实现 方式 是 ， 在 子 模型 和 父 模型 之 
间 建 立 隐 含 的 一 对 一 关系 。 


























9 个 必须 的 位 置 参数 ， 与 之 关联 的 类 。 这 与 ForeignKey 的 那个 参数 作用 完全 一 样 ， 参 数 也 一 样 (不管 是 递归 
关系 还 是 惰性 关系 ) 。 如 果 不 为 OneToOneField 指定 related_name 参数 ，Django 默认 使 用 当前 模型 名 称 的 小 
写 形式 。 以 下 述 代码 为 例 : 
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from django.conf import settings 
from django.db import models 


class MySpecialUser(models.Model): 
user = models.OneToOneField(settings.AUTH_USER_MODEL) 
supervisor = models.OneToOneField(settings.AUTH_USER_MODEL, 
related_name=' supervisor_of') 








得 到 的 User 模型 具有 下 述 属性 : 


>>> USser = User.objects.get(pk=1) 


>>> hasattr(user, 'myspecialuser') 
True 
>>> hasattr(user, 'supervisor_of') 


True 








如 果 关 联 的 表 中 没有 关联 的 记录 ， 访 问 反 向 关系 时 会 抛 出 DoesNotExist 
cialUser 指派 的 主管 : 


>>> User.supervisor_of 
Traceback (most recent call Last) : 


DoesNotExist: User matching query does not exist. 


OneToOneField 接受 的 参数 与 ForeignKey 完全 一 样 ， 此 外 还 有 一 个 参数 。 


parent_Link 


异常 。 假 如 某 个 























j 户 没有 通过 MySpe- 




















设 为 True， 并 且 在 继承 自 另 一 个 具体 模型 的 模型 中 使 用 时 ， 指 明 这 个 字段 
子 类 化 创建 的 额外 的 OneTooneFieLd。 使 用 示例 参见 B.9.3 节 

















于 链接 




















回 到 父 类 ， 而 不 是 通常 由 

























































































A.5 模型 元 数据 选项 
表 A-3 列 出 可 以 在 模型 内 部 的 class Meta 中 使 用 的 全 部 模型 元 数据 选项 。 各 选项 的 详细 说 明和 示例 参阅 
Django 文档 。 
表 A-3， 模 型 元 数据 选项 
选项 说 明 
abstract 设 为 True 时 表明 模型 是 抽象 基 类 。 
app_Label 如 果 定 义 模 型 的 应 用 不 在 INSTALLED_APPS 中 ， 必 须 指 定 所 属 的 应 用 。 
db_table 模型 使 用 的 数据 库 表 名 称 。 
A 模型 使 用 的 数据 库 表 空间 。 默 认为 项 目的 DEFAULT_TABLESPACE 设置 (如 
一 果 设 定 了 ) 。 如 果 数 据 库 后 端 不 文 持 表 空间 ， 忽 略 这 个 选项 。 
default_related name 关联 的 对 象 回 指 这 个 模型 默认 使 用 的 名 称 。 默 认为 <model_name>_set。 
模型 中 可 排序 字段 的 名 称 ， 通 常 是 一 个 DateFieLd、DateTimeFieLd 或 
get_Latest_by 
IntegerField, 
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( 续 ) 














选项 说 明 
managed 默认 为 True， 即 让 Django 在 迁移 中 创建 适当 的 数据 库 表 ， 并 在 执行 








flush 管理 命令 时 把 表 删 除 。 





























order_with_respect_to 标记 对 象 为 可 排序 的 ， 排 序 依 据 是 指定 的 字段 。 

ordering 对 象 的 默认 排序 ， 获 取 对 象 列 表 时 使 用 。 

permissions 创建 对 象 时 写 入 权限 表 的 额外 权限 。 

default_permissions 默认 为 ('add'，'change'，'delete')。 

proxy 设 为 True 时 ， 定 义 为 另 一 个 模型 的 子 类 的 模型 视 作 代理 模型 。 








指明 是 否 让 Django 使 用 1.6 版 之 前 的 django.db.models.Model.save() 算 
select_on_save 二 





























法 。 
unique_together 设 定 组 合 在 一 起 时 必须 唯一 的 多 个 字段 名 称 。 
index_together 设 定 在 一 起 建立 索引 的 多 个 字段 名 称 。 
verbose_name 为 对 象 设 定 人 类 可 读 的 名 称 (单数 ) 。 
verbose_name_plural 设 定 对 象 的 复数 名 称 。 
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附录 B 数据 库 API 参考 指南 














Django 的 数据 库 API 是 附录 A 所 述 模型 API 的 另 一 半 。 定 义 好 模型 之 后 ， 便 可 以 使 用 这 个 API 访问 数据 
库 。 本 书 举 了 很 多 使 用 这 个 API 的 例子 ， 这 一 篇 附录 详 述 各 个 选项 。 


本 篇 附录 以 下 述 博客 应 用 程序 中 的 模型 为 例 : 



































from django.db import models 


class Blog(models.Model): 
name = models.CharField(max_length=100) 
tagline = models.TextField() 


def _str_(self): 
return self.name 


class Author(models.Model): 
name = models.CharField(max_length=50) 
email = models.EmailField() 


def _str__(self): 
return self.name 


class Entry(models.Model): 
blog = models.ForeignKey(Blog) 
headline = models.CharField(max_length=255) 
body_text = models.TextField() 
pub_date = modeLs.DateFieLd() 
mod_date = models.DateField() 
authors = models.ManyToManyField(Author) 
n_Comments = models.IntegerField() 
n_pingbacks = models.IntegerField() 
rating = models.IntegerField() 


def _ str_(self): 
return self.headline 


B.1 创建 对 象 





Django 采用 一 种 直观 的 方式 以 Python 对 象 表述 数据 库 表 中 的 数据 : 一 个 模型 类 表示 一 个 数据 库 表 ， 而 模型 
类 的 实例 表示 表 中 的 具体 记录 。 


创建 对 象 的 方法 是 把 关键 字 参 数 传 给 模型 类 ， 然 后 调用 save() 方法 将 其 存 人 数据 库 。 


















































假设 模型 保存 在 mysite/blog/models.py 文件 中 ， 下 面 举 个 例子 : 


>>> from blog.models import BLog 
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>>> b = Blog(name='Beatles BLog' ，tagLine='ALL the Latest Beatles news.') 
>>> b.save() 


在 背后 ， 这 上 段 代码 执 行 一 个 SQL INSERT 语句 。 除 非 明 确 调用 save() 方法 ， 否 则 Django 不 会 触及 数据 库 。 
save() 方法 没有 返回 值 。 
如 果 想 在 一 步 中 创建 并 保存 对 象 ， 使 用 create() 方法 。 
































B.2 保存 对 象 的 变动 





若 想 保存 数据 库 中 现 有 对 象 的 变动 ， 使 用 save() 方法 。 
假设 Blog 的 一 个 实例 bs 已 经 存 人 数据 库 ， 下 述 示例 修改 它 的 名 称 ， 然 后 更 新 数据 库 中 的 记录 : 








>>> b5.name = 'New name' 
>>> b5.save() 


在 背后 ， 这 段 代码 执行 一 个 SQL UPDATE 语句 。 除 非 明确 调用 save() 方法 ， 和 否则 Django 不 会 触及 数据 库 。 





B.2.1 保存 ForeignKey 和 ManyToManyField 字段 


更 新 ForeignkKey 字段 的 方式 与 常规 的 字段 完全 一 样 ， 只 需 把 正确 类 型 的 对 象 赋值 给 字段 。 假 设 相应 的 Entry 
和 Blog 实例 已 经 存 人 数据 库 (这 样 才能 将 其 检索 出 来 ) ， 下 述 示例 更 新 Entry 实例 entry 的 blog 属性 : 














>>> from blog.models import Entry 

>>> entry = Entry.objects.get(pk=1) 

>>> cheese_blog = Blog.objects.get(name="Cheddar Talk") 
>>> entry.blog = cheese_blog 

>>> entry.save() 














更 新 ManyToManyField 字段 的 方式 稍 有 不 同 ， 要 在 字段 上 调用 add() 方法 ， 把 记录 添加 到 关系 中 。 下 述 示例 把 
Author 实例 joe 添加 到 entry 对 象 上 : 





>>> from blog.models import Author 
>>> joe = Author .objects.create(name="Joe") 
>>> entry.authors.add(joe) 


如 果 想 一 次 性 为 ManyToManyField 字段 添加 多 个 记录 ， 调 用 add() 方法 时 传 入 多 个 参数 ， 如 下 所 示 : 


>>> john = Author .objects.create(name="John") 

>>> pauL = Author .objects.create(name="Paul") 

>>> george = Author .objects.create(name="George") 
>>> ringo = Author.objects.create(name="Ringo") 
>>> entry.authors.add(john, paul, george, ringo) 


如 果 赋 值 或 添加 的 对 象 类 型 不 对 ，Dijango 会 报错 。 


B.3 检索 对 象 


若 想 从 数据 库 中 检索 对 象 ， 通 过 模型 类 的 Manager 实例 构建 一 个 QuerySet。 
QuerySet 实例 表示 数据 库 中 对 象 的 集合 。 在 Queryset 上 可 调用 零 个 、 一 个 或 多 个 过 滤器 (filter) 。 过 滤器 根 











336 - 附录 B 数据 库 API 参考 指南 





据 指定 参数 缩 窗 查询 结果 。 用 SQL 术语 来 说 ，Queryset 相当 于 SELECT 语句 ， 而 过 滤器 相当 于 限制 子 句 ， 如 
WHERE 或 LIMIT。 





QuerySet 通过 模型 的 Manager 得 到 。 一 个 模型 至 少 有 一 个 Manager ， 默 认 名 为 objects。Manager 可 以 直接 通 
过 模型 类 访问 ， 例 如 ; 

















>>> BLog.objects 
<django.db.models.manager .Manager object at ...> 
>>> b = Blog(name='Foo', tagline='Bar') 

>>> b.objects 

Traceback: 


AttributeError: "Manager isn't accessible via Blog instances." 


B.3.1 检索 全 部 对 象 
从 表 中 检索 对 象 最 简单 的 方式 是 获取 全 部 对 象 。 为 此 ， 在 Manager 上 调用 atLL() 方法 : 























>>> all_entries = Entry.objects.all() 


all() 方法 返回 一 个 Queryset 对 象 ， 包 含 数据 库 表 中 的 全 部 对 象 。 








B.3.2 使 用 过 滤器 检索 特定 对 象 


all() 方法 返回 的 Queryset 对 象 包 含 数据 库 表 中 的 全 部 对 象 。 然 而 ， 通 常 只 需 选 取 其 中 部 分 对 象 。 











为 此 ， 要 添加 过 滤 条 件 ， 精 选 得 到 的 Queryset。 最 常用 的 精 选 方法 是 : 








。 filter(**kwargs): 返回 一 个 新 的 QuerySet 对 象 ， 包 含 匹 配 指定 查找 参数 的 对 象 。 
。 exclude(**kwargs): 返回 一 个 新 的 QuerySet 对 象 ， 包 含 不 匹配 指定 查找 参数 的 对 象 。 














查找 参数 (上述 函数 签名 中 的 **kwargs) 应 该 满足 B.3.6 市 所 述 的 格式 。 


串联 过 滤器 














精 选 QuerySet 后 得 到 的 还 是 QuerySset， 因 此 可 以 通过 串联 ， 进 一 步 精 选 。 例 如 : 











>>> Entry.objects.filter( 
headline__startswith="'What' 
... ).exclude( 
pub_date__gte=datetime.date. today() 
... ).filter(pub_date gte=datetime(2005, 1, 30) 
。) 


上 述 代码 先 获 取 包 含 数据 库 表 中 全 部 对 象 的 Queryset， 然 后 添加 一 个 过 滤器 ， 排 除 一 些 对 象 ， 最 后 再 添加 一 
个 过 滤器 。 最 终 得 到 的 Queryset 包含 标题 以 What 开头、 在 2005 年 1 月 30 日 至 今天 之 间 发 布 的 文章 。 














过 滤 后 的 QuerySet 是 独一无二 的 


每 次 精 选 QuerySset 得 到 的 都 是 全 新 的 QuerySet， 与 之 前 的 QuerySet 没有 任何 联系 。 精 选 后 得 到 的 QuerySet 
是 独立 的 、 截 然 不 同 的 ， 可 以 存储 、 使 用 和 复 用 。 














例如 : 
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>>> q1 = Entry.objects.filter(headline__startswith="What") 
>>> q2 = q1.excLude(pub_date_ gte=datetime.date.today()) 
>>> q3 = q1.fiLiLter(pub_date_ gte=datetime.date.today()) 


这 三 个 Queryset 是 相互 独立 的 。 第 一 个 Queryset 包含 所 有 标题 以 “What 开头 的 文章 ， 第 二 个 Queryset 是 第 
一 个 的 子 集 ， 多 了 一 个 条 件 ， 即 排除 pub_date 为 今天 或 未 来 某 天 的 记录 ， 第 三 个 QuerysSet 是 第 一 个 的 子 
集 ， 多 了 一 个 条 件 ， 即 只 选择 pub_date 为 今天 或 未 来 某 天 的 记录 。 在 后 续 精 选 的 过 程 中 ， 第 一 个 Query- 
Set (q1) 不 受 影响 。 


























QuerySset 是 情 性 的 





























Queryset 是 惰性 的 ， 创 建 QuerySet 不 涉及 任何 数据 库 活动 。 你 可 以 一 直 串 联 过 滤器 ，Django 并 不 会 执行 查 
询 ， 真 正 的 查询 等 到 求 值 Queryset 时 才 执 行 。 下 面 举 个 例子 : 











>>> q = Entry.objects.filter(headline_ _startswith="What") 
>>> q = q.filter(pub_date__lte=datetime.date.today()) 

>>> q = q.exclude(body_text__icontains="food") 

>>> print(q) 




















看 起 来 这 段 代码 好 像 访问 了 三 次 数据 库 ， 但 其 实 只 访问 了 一 次 一 一 执行 最 后 一 行 时 (print(q)) 。 通 常 ， 直 
到 查看 Queryset 的 结果 时 才 会 从 数据 库 中 获取 数据 。 届 时 ， 求 值 Queryset， 访 问 数据 库 。 




















J 

















B.3.3 使 用 get() 方法 检索 单个 对 象 


fitLter() 方法 总 是 返回 一 个 QuerySet ， 即 便 只 有 一 个 对 象 匹配 查询 也 是 如 此 (只 有 一 个 元 素 的 QuerySet) 。 











如 果 知 道具 有 一 个 对 象 匹配 查询 ， 可 以 在 Manager 上 调用 get() 方法 ， 直 接 返 回 那个 对 象 : 























>>> one_entry = Entry.objects.get(pk=1) 
与 filter() 方法 一 样 ，get() 方法 的 参数 可 以 指定 任何 查询 表达 式 ， 详 情 参见 B.3.6 疗 。 


注意 ，get() 和 fitter() 对 切片 [6] 的 处 理 方式 有 所 不 同 。 如 果 没 有 匹配 查询 的 结果 ，get() 抛 出 DoesNotEx- 
ist 异常 。 这 个 异常 是 执行 查询 那个 模型 类 的 属性 ， 因 此 ， 在 上 述 代 码 中 ， 如 果 没有 主键 为 1 的 Entry 对 
象 ，Django 抛 出 Entry.DoesNotExist 异常 。 




















类 似 地 ， 如 果 get() 返回 多 个 对 象 ，Django 也 会 报错 。 此 时 ， 抛 出 MuLtiptLeobjectsReturned 异常 (也 是 模型 
类 的 属性 ) 。 





B.3.4 其 他 QuerySet 方法 


从 数据 库 中 检索 对 象 最 常 使 用 的 方法 是 aLL()、get()、fitLter() 和 exclude()。 然 而 ， 可 用 的 方法 远 非 这 几 
个 。 全 部 QuerySet 方法 参见 QuerySet API 参考 指南 。 








B.3.5 限制 QuerySet 的 大 小 

















大 想 限制 结果 的 数量 ， 使 用 Python 的 数组 切片 句法 。 这 等 效 于 SQL 的 LIMIT 和 OFFSET 子 句 。 














例如 ， 返 回 前 5 个 对 象 (LIMIT 5) : 
>>> Entry.objects.all()[:5] 


下 述 代 码 返回 第 6 个 到 第 10 个 对 象 (OFFSET 5 LIMIT 5) : 
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>>> Entry.objects.all()[5:10] 


不 支持 负数 索引 (如 Entry.objects.all()[-1]) 。 


通常 ， 切 割 QuerySet 得 到 一 个 新 的 QuerySet， 而 且 不 求 值 查询 。 使 用 Python 的 步 进 切 片 句 法 时 除外 。 例 





如 ， 下 述 











代码 会 执行 查询 ， 因 为 要 在 前 10 个 对 象 中 间隔 一 个 跳出 一 个 对 象 ， 构 成 列表 : 








>>> Entry.objects.all()[:10:2] 








若 想 


例如 ， 下 述 代 码 返 











依 索 单个 对 象 (如 SELECT foo FROM bar LIMIT 1) ， 而 非 一 个 列表 ， 别 用 切片 ， 要 用 单个 索引 。 











回 按 标 题字 母 顺序 排列 后 的 第 一 个 Entry 对 象 : 





>>> Entry.objects.order _by('headLine ')[0] 





这 基本 上 等 价 于 : 





>>> Entry.objects.order_by('headline')[0:1].get() 





然而 ， 要 注意 ， 如 果 没 有 匹配 指定 条 件 的 对 象 ， 前 者 抛 出 IndexError， 而 后 者 抛 出 DoesNotExist。 详 情 参 见 
get() 方法 。 


B.3.6 按 字段 查找 





按 字段 查找 相当 于 在 SQL 中 添加 WHERE 子 句 ， 方 法 是 在 filter()、exclude() 和 get() 方法 中 指定 关键 字 参 
数 。 查 找 关键 字 参 数 的 基本 句法 是 field__lookuptype=value (中 间 是 两 个 下 划 线 ) 。 例 如 : 





>>> Entry.objects.filter(pub_date__lte='2006-01-01') 


(基本 上 ) 相当 于 下 述 SQL: 





SELECT * FROM blog_entry WHERE pub_date <= '2006-01-01'; 


查找 参数 





FP 指 定 的 字段 必须 是 模型 字段 的 名 称 。 不 过 有 个 例外 : 按 ForeignKey 字段 查找 时 ， 字 上 段 的 名 称 后 曾 

















要 添加 _id。 此 时 ， 参 数 的 值 应 该 是 外 联 模型 主键 的 原始 值 。 例 如 : 


>>> Entry.objects.filter(blog_id=4) 


传人 无 效 的 关键 字 参 数 时 ， 查 找 函 数 殷 出 TypeError。 
按 字段 查找 可 用 的 条 件 如 下 : 


exact 
Tiexact 
contains 
icontains 
in 

gt 

gte 

lt 

lte 


startswith 
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。 istartswith 
。 endswith 
。 iendswith 
。 range 

。 year 

。 month 

。 day 

。 week day 
。 hour 

。 minute 

。 second 

。 isnull 

。 search 

。 regex 


。 iregex 





详细 说 明和 示例 参见 文档 。 


B.3.7 跨 关系 查找 











Django 提供 了 强大 而 直观 的 关系 查找 方式 ， 在 背后 会 自动 执行 SQL JOIN 查询 。 若 想 跨 关 系 ， 只 需 使 用 两 个 
下 划 线 连接 各 模型 中 的 字段 名 称 ， 直 到 得 到 所 需 的 字段 为 止 。 


下 述 示例 在 name 为 'Beatles Blog' 的 Blog 中 检索 所 有 Entry 对 象 ; 




















>>> Entry.objects.filter(blog_ name='Beatles Blog') 


关系 的 跨度 范围 不 限 。 




















反 过 来 跨 也 可 以 。 引 用 反 向 关系 的 方法 是 使 用 小 写 的 模型 名 称 。 
下 述 示例 检索 至 少 有 一 个 Entry 对 象 的 headline 包含 'Lennon' 的 Blog 对 象 : 





>>> Blog.objects.filter(entry__headline__contains='Lennon') 





通过 多 个 关系 过 滤 时 ， 如 果 某 个 中 间 模 型 没有 匹配 过 滤 条 件 的 值 ，Django 假设 有 一 个 空 的 对 象 无效， 所 有 
值 都 为 NULL) 。 也 就 是 说 ， 此 时 不 会 抛 出 异常 。 以 下 述 过 滤器 为 例 : 

















Blog.objects.filter(entry__authors__name='Lennon') 


(假设 有 个 关联 的 Author 模型 ) 如 果 没 有 与 文章 关联 的 author 对 象 ，Django 假设 也 没有 相应 的 name， 以 防 
因 缺 少 author 对 象 而 抛 出 异常 。 通 常 ， 这 正 是 所 需 的 行为 。 然 而 ， 使 用 isnull 时 可 能 会 让 人 困惑 。 因 此 : 











Blog.objects.filter(entry__authors__name__isnull=True) 


将 返回 author 的 name 值 为 空 的 BLog 对 象 ， 以 及 entry 的 author 值 为 空 的 对 象 。 如 果 不 想 要 后 面 那 部 分 对 
象 ， 代 码 可 以 这 样 写 : 


Blog.objects.filter(entry__authors__isnull=False, entry__authors__name__isnull=True) 
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跨 多 值 关系 














基于 ManyToManyField 或 反 向 ForeignKey 过 滤 时 ， 可 能 会 用 到 两 种 过 滤器 。 以 BLog 和 En 
多 ) 关系 为 例 。 我 们 可 能 想 找 出 标题 中 带 有 “Lennon”， 而 且 发 布 于 2008 年 的 文章 所 属 的 





或 者 ， 找 出 标题 


博客 关联 着 多 篇 文章 ， 所 以 在 某 些 情况 下 可 能 需要 做 这 两 种 查询 。 


多 对 多 关系 中 也 


对 这 些 情况 来 说 ， 

















多 次 调用 filter() 用 于 进一步 筛选 对 象 ， 但 是 对 多 值 关 系 来 说 ， 过 滤 的 是 
一 定 是 前 一 个 filter() 调用 选 出 的 对 象 。 

















带 有 “Lennon” 的 文章 所 属 的 博客 ， 同 时 再 找 出 发 布 于 2008 年 的 文章 所 



































try 之 间 的 (一 对 


属 的 博客 。 因 为 一 个 











这 种 需求 。 假 如 Entry 模型 有 个 ManyToManyFieLd， 名 为 tags， 我 们 可 能 想 分 别 找 出 与 “mu- 
sic" 和 “bands” 关 联 的 文章 ， 或 者 找 出 标签 为 “music”， 而 且 状 态 为 "public" 的 文章 。 








Django 处 理 filter() 和 exctude() 的 方式 是 一 致 的 。filter() 调用 中 的 参数 在 过 滤 时 同时 
匹配 ， 找 出 满足 全 部 条 件 的 对 象 。 














这 样 说 可 能 有 点 难以 理解 ， 希 望 通过 示例 能 让 你 弄 明 白 。 为 了 找 出 标题 中 带 有 “Lennon”， 
的 文章 (同时 满足 两 个 条 件 的 文章 ) 所 属 的 博客 ， 可 以 这 样 写 : 





Blog.objects.filter(entry__headline__contains='Lennon', 


entry__pub_date year=2008) 





王 何 与 主 模型 链接 的 对 象 ， 而 不 必 





而 且 发 布 于 2008 年 














为 了 找 出 标题 中 带 有 “Lennon” 的 文章 所 属 的 博客 ， 同 时 再 找 出 发 布 于 2008 年 的 文章 所 属 的 博客 ， 可 以 这 样 





Blog.objects.filter(entry__headline__contains='Lennon').filter( 


entry__pub date year=2008) 


























假设 只 有 一 个 博客 中 有 标题 中 包含 “Lennon” 的 文章 和 发 布 于 2008 年 的 文章 ， 但 是 2008 恒 
中 都 没有 “Lennon”。 那 么 ， 第 一 个 查询 不 返回 任何 博客 ， 而 第 二 个 查询 返回 那个 博客 。 


在 第 二 个 示例 中 ， 第 一 个 过 滤器 限制 查询 集合 ， 只 包含 标题 中 带 有 “Lennon ”的 文章 所 属 的 博客 ， 第 二 个 过 滤 
器 进一步 限制 查询 集合 ， 限 制 博客 中 还 要 有 发 布 于 2008 年 的 文章 。 














发 布 的 文章 ， 标 题 












































第 二 个 过 滤器 选择 的 文章 可 能 与 第 一 个 过 滤器 选择 的 相同 ， 也 可 能 不 同 。 每 个 过 滤器 过 滤 的 都 是 BLog 对 象 集 








合 ， 而 非 Entry 对 象 集合 。 


这 些 行为 也 适用 于 exclude(): 一 个 exclude() 调用 中 的 所 有 条 件 同 时 应 用 到 一 个 实例 上 (前 提 是 条 件 针对 的 


是 相同 的 多 值 关 系 ) 。 连 续 调 用 filter() 或 exclude() 处 理 相同 的 关系 时 ， 后 本 





关联 对 象 集合 。 























B.3.8 过 滤器 可 以 引用 模型 中 的 字段 


i 的 调用 过 滤 的 可 能 是 不 同 的 


目前 所 举 的 例子 在 过 滤器 中 都 是 比较 模型 字段 的 值 和 常量 。 那 么 ， 如 果 想 比较 同一 个 模型 中 的 两 个 字段 的 值 


呢 ? 


为 此 ，Django 提供 了 F 表达 式 。 在 查询 


























引用 ， 以 便 比 较 同一 个 模型 实例 中 的 两 个 字段 。 





例如 ， 为 了 找 出 讨 











Ph，F() 的 实例 引用 一 个 模型 字段 。 在 查询 过 滤器 中 可 以 使 用 这 样 的 





论 数量 比 pingback 多 的 博客 文章 ， 可 以 构建 一 个 F() 对 象 ， 引 用 pingback 数量 ， 然 后 在 查 





询 中 使 用 那个 F() 对 象 : 


>>> from django.db.modeLs import F 


>>> Entry.objects.filter(n_comments gt=F('n_pingbacks')) 
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Django 支持 F() 对 象 与 常量 和 其 他 F() 对 象 做 加 、 减 、 乘 、 除 、 模 和 和 窜 运算。 为 了 找 出 评论 数量 是 pingback 
两 倍 多 的 博客 文章 ， 可 以 这 样 修改 查询 : 











>>> Entry.objects.filter(n_comments gt=F('n_pingbacks')* 2) 


若 想 找 出 得 分 低 于 pingback 和 评论 数量 之 和 的 文章 ， 可 以 这 样 查询 : 





>>> Entry.objects.filter(rating__lt=F('n_comments') + F('n_pingbacks')) 























此 外 ， 还 可 以 在 F() 对 象 中 使 用 双 下 划 线 表示 法 跨 关系 。 此 时 ， 为 了 访问 关联 的 对 象 ， 会 引入 适当 的 联结 
询 。 


例如 ， 若 想 检索 作者 姓名 与 博客 名 称 一 样 的 文章 ， 可 以 这 样 查询 : 








>>> Entry.objects.filter(authors__name=F('blog__name')) 


遇 到 日 期 和 日 期 时 间 字 段 ， 可 以 加 上 或 减 去 一 个 timedelta 对 象 。 下 述 查 询 返 回 发 布 三 天 后 修改 过 的 文章 








>>> from datetime import timedelta 
>>> Entry.objects.filter(mod date gt=F('pub date') + timedelta(days=3)) 


通过 .bitand() 和 .bitor()， 还 可 以 让 F() 对 象 支持 位 运算 ， 例 如 : 


>>> F('somefield').bitand(16) 


B.3.9 pk 简 记 法 





为 了 方便 ，Django 为 主键 提供 了 简 记 法 一 一 pk。 








在 Blog 示例 模型 中 ， 主 键 是 id 字段 ， 因 此 下 述 三 个 语句 是 等 效 的 : 





>>> Blog.objects.get(id exact=14) # 明确 指定 
>>> Blog.objects.get(id=14) # 了 暗含 __exact 
>>> Blog.objects.get(pk=14) # pk 上 暗 指 id_ exact 














pk 不 限于 只 能 在 _exact 查询 中 使 用 ， 任 何 查 询 词 条 都 可 以 与 pk 联合 起 来 ， 在 模型 的 主键 上 执行 查询 : 











# 获取 ID 为 1、4 和 7 的 博客 文章 
>>> Blog.objects.filter(pk__in=[1,4,7]) 


# 获取 ID > 14 的 博客 文章 
>>> Blog.objects.filter(pk__gt=14) 


在 联结 查询 中 也 可 以 使 用 pk。 例 如 ， 下 述 三 个 语句 是 等 效 的 : 


>>> Entry.objects.filter(blog id exact=3) # 明确 指定 
>>> Entry.objects.fiLLter(bLog__id=3) # 暗含 _exact 
>>> Entry.objects.fiLter(bLog__pk=3) # __pk 上 暗 指 __id__exact 


B.3.10 转 义 LIKE 语句 中 的 百 分 号 和 下 划 线 


按 字段 查找 时 ， 如 果 得 到 的 SQL 包含 LIKE 语句 (iexact、contains、icontains、startswith、is- 
Partsuiths endswith 和 iendswith) ，LIKE 语句 中 的 两 个 特殊 字符 会 是， 百 分 号 和 下 划 线 。 (在 LIKE 
语句 中 ， 百 分 号 是 匹配 多 个 字符 的 通配符 ， 而 下 划 线 是 匹配 单个 字符 的 通配符 。) 
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这 样 ， 查 询 才能 按 预期 正确 运行 ， 不 出 意外 。 例 如 ， 若 想 检索 标题 中 包含 百 分 号 的 文章 ， 像 正常 字符 那样 使 
用 百 分 号 即 可 : 











>>> Entry.objects.filter(headline_ _contains='%') 














转 义 由 Django 负责 ， 得 到 的 SQL 类 似 下 面 这 样 : 





SELECT ... WHERE headline LIKE '%\%%'; 





下 划 线 同 理 。 百 分 号 和 下 划 线 都 由 Django 默默 处 理 。 





B.3.11 查询 集合 缓存 
为 了 减少 数据 库 访问 ， 每 个 Queryset 都 包含 缓存 。 为 了 写 出 最 高 效 的 代码 ， 一 定 要 理解 缓存 的 工作 原理 。 


对 新 建 的 QuerySet 来 说 ， 缓 存 是 空 的 。 首 次 求 值 Queryset 时 (因此 访问 了 数据 库 ) ，Django 把 查询 结果 保 
存在 QuerySet 的 缓存 中 ， 然 后 返回 明确 请 求 的 对 象 (例如 ， 和 迭代 Queryset 时 返回 下 一 个 元 素 ) 。 后 续 再 求 
值 Queryset， 则 复 用 缓存 的 结果 。 







































































记 住 有 这 么 一 个 缓存 ， 如 果 对 QuerysSet 处 理 不 当 ， 你 会 深 受 其 害 。 例 如 ， 下 述 两 个 语句 会 创建 两 个 Query- 
set， 求 值 后 就 丢弃 : 








>>> print([e.headline for e in Entry.objects.all()]) 
>>> print([e.pub_date for e in Entry.objects.all()]) 








也 就 是 说 ， 相 同 的 数据 库 查 询 会 执行 两 次 ， 因 此 数据 库 负载 也 加 倍 了 。 此 外 ， 两 次 得 到 的 结果 也 可 能 不 同 ， 
因为 在 两 次 查询 的 间隙 可 能 增加 或 删除 了 Entry 对 象 。 


为 了 避免 这 种 问题 ， 只 需 保 存 QuerySet， 然 后 复 用 : 


>>> queryset = Entry.objects.all() 
>>> print([p.headline for p in queryset]) # 求 值 查询 结合 
>>> print([p.pub_date for p in queryset]) # 复 用 缓存 中 的 求 值 结 果 


查询 集合 何 时 不 缓存 





查询 集合 并 非 始终 缓存 结果 。 求 值 查询 集合 的 一 部 分 时 会 检查 缓存 ， 如 果 未 填充 ， 后 续 查 询 返 回 的 结果 不 会 
缓存 。 具 体 而 言 ， 通 过 数组 切片 或 索引 限制 查询 集合 的 大 小 时 ， 不 会 填充 缓存 。 


例如 ， 在 查询 集合 上 多 次 获取 某 个 索引 时 ， 每 一 次 都 会 查询 数据 库 

















>>> queryset = Entry.objects.all() 
>>> print queryset[5] # 查询 数据 库 
>>> print queryset[5] # 再 次 查询 数据 库 





然而 ， 如 果 整 个 查询 集合 已 经 求 值 ， 则 会 使 用 缓存 : 








>>> queryset = Entry.objects.all() 

>>> [entry for entry in queryset] # 查询 数据 库 
>>> print queryset[5] # 使 用 缓存 
>>> print queryset[5] # 使 用 缓存 


下 面 举例 说 明 其 他 会 导致 整个 查询 集合 求 值 的 操作 〈 进 而 填充 缓存 ) : 








>>> [entry for entry in queryset] 
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>>> bool(queryset) 
>>> entry in queryset 
>>> list(queryset) 


B.4 使 用 Q 对 象 执行 复杂 的 查找 


filter() 等 的 关键 字 参 数 指定 的 条 件 是 并 联 在 一 起 的 ， 如 果 需 要 执行 更 复杂 的 查询 (例如 ,使 用 OR 语句 查 
询 ) ， 可 以 使 用 Q 对 象 。 


Q 对 象 (django.db.modets.Q) 用 于 封装 一 系列 关键 字 参 数 。 指 定 这 些 关 键 字 参 数 的 方式 与 前 述 按 字 段 查 询 一 
样 。 


例如 ， 下 述 0 对 象 封装 一 个 LIKE 查询 : 












































from django.db.models import Q 
Q(question__startswitith= 'What ') 


Q 对 象 可 以 使 用 & 和 | 运算 符 结 合 在 一 起 。 此 时 ， 两 个 Q 对 象 产 出 一 个 新 Q 对 象 。 


例如 ， 下 述 语句 产 出 一 个 Q 对 象 ， 通 过 oOR 把 两 个 "question__startswith" 查询 合并 到 一 起 : 











Q(question_startswith='Nho') | Q(question_ _startswith='What') 
等 效 的 SQL WHERE 子 句 如 下 : 


WHERE question LIKE 'Who%' OR question LIKE "What% 























使 用 & 和 | 运算 符 ， 再 利用 括号 分 组 ， 可 以 组 合 出 任意 复杂 的 查询 。 此 外 ，Q 对 象 还 可 以 使 用 ~ 运算 符 取 
反 。 因 此 ， 可 以 把 常规 的 查询 和 取 反 (NOT) 查询 合并 到 一 起 : 























Q(question _startswith='Who') | ~Q(pub_date year=2005) 


接受 关键 字 参 数 的 查找 函数 (如 fitter()、exclude()、get()) 都 可 以 通过 位 置 (无 名 ) 参数 传人 一 个 或 多 
个 Q 对象。 如 果 把 多 个 Q 对 象 传 给 查找 函数 ， 各 个 Q 对 象 并 联 在 一 起 。 例 如 








PoLL.objects .get( 

Q(question__startswith='Who'), 

Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)) 
) 


这 段 代 码 基本 上 相当 于 下 述 SQL: 





SELECT * from polls WHERE question LIKE 'Who%' AND (pub_ date = '2005-05-02' OR pub_date = 
'2005-05-06') 





查找 函数 可 以 混用 对 象 和 关键 字 参 数 。 传 给 查找 函数 的 所 有 参数 (关键 字 参 数 或 0 对 象 ) 并 联 在 一 起 。 然 
而 ， 如 果 有 Q 对 象 ， 必 须 放 在 关键 字 参 数 前 面 。 例 如 : 

















PoLL.objects .get( 
Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)), 
question__startswith='Who') 


这 是 有 效 的 查询 ， 与 前 例 作 用 相同 。 但 是 ， 下 述 查 询 是 无 效 的 。 


# 无 效 查询 
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PoLL.objects .get( 
question__startswith='Who', 
Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6))) 


B.5 比较 对 象 


若 想 比较 两 个 模型 实例 ， 使 用 标准 的 Python 比较 运算 符 〈 双 等 号 ，==) 即 可 。 在 背后 比较 的 是 两 个 模型 实例 
的 主键 值 。 











以 前 面 的 Entry 模型 为 例 ， 下 述 两 个 语句 是 等 效 的 ; 











>>> some_entry == other_entry 
>>> some_entry.id == other_entry.id 














模型 的 主键 不 是 id 也 没 问 题 。 不 管 主 键 的 名 称 是 什么 ， 比 较 的 始终 是 主键 。 假 如 模型 的 主键 字段 名 为 
name ， 下 述 两 个 语句 是 等 效 的 : 





>>> Some_obj == other_obj 
>>> some_obj.name == other_obj.name 
B.6 删除 对 象 





为 了 方便 ， 删除 方法 名 为 delete()。 这 个 方法 立即 删除 对 象 ， 而 且 没 有 返回 值 。 例 如 : 























e.delete() 








对 象 也 可 以 批量 删除 。Queryset 都 有 delete() 方法 ， 其 作用 是 删除 Queryset 中 的 所 有 成 员 。 
例如 ， 下 述 代 码 删除 pub_date 的 年 份 为 2005 的 所 有 Entry 对 象 : 




















Entry.objects.fiLLter(pub_ date_ year=2005) .detLete() 

















注意 ， 只 要 可 能 ， 批 量 删 除 操作 纯粹 使 用 SQL 语句 删除 ， 因 此 在 此 期 间 不 一 定 会 调用 各 个 实例 的 delete() 
方法 。 如 果 在 模型 类 中 自 定 义 了 delete() 方 法， 想 调用 它 的 话 ， 必 须 逐 个 删除 模型 实例 〈 例 如， 和 迭代 Query- 
Set， 在 各 个 对 象 上 调用 delete()) ， 而 不 能 在 QuerySset 上 调用 delete() 方法 批量 删除 。 






































删除 对 象 时 ，Django 默认 模拟 SQL 约束 ON DELETE CASCADE 的 行为 。 也 就 是 说 ， 如 果 一 个 对 象 通过 外 键 指向 
要 删除 的 对 象 ， 它 自身 也 会 被 删除 。 例 如 : 


b = Blog.objects.get(pk=1) 
# 删除 博客 及 其 中 的 所 有 “Entry ”对 象 
b.delete() 





这 种 层 县 行为 可 以 通过 ForeignKey 的 on_delete 参数 自 定义 。 


























注意 ，delete() 是 QuerySet 上 唯一 不 通过 Manager 开放 的 方法 。 这 是 一 种 防护 机 制 ， 以 防 你 不 小 心 调用 En- 
try.objects.delete()， 把 所 有 文章 都 删 掉 。 如 果 确 实 想 删除 所 有 对 象 ， 要 明确 请 求 完整 的 查询 集合 : 





















































Entry.objects.all().delete() 


B.7 复制 模型 实例 


没有 内 置 的 方法 能 复制 模型 实例 ， 但 是 能 轻易 创建 所 有 字段 的 值 都 一 样 的 新 实例 。 最 简单 的 方法 是 把 pk 设 为 
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None。 以 Blog 模型 为 例 : 


>>> blog = Blog(name='My blog', tagline='Blogging is easy') 
>>> blog.save() # blog.pk == 1 

>>> blog.pk = None 

>>> blog.save() # blog.pk == 2 


如 果 涉 及 继承 ， 情 况 要 复杂 一 些 。 以 Blog 的 子 类 为 例 : 


>>> CLass ThemeBLog(BLog) : 
theme = models.CharField(max_length=200) 


>>> django_blog = ThemeBlog(name='Django', tagline='Django is easy', theme='python') 
>>> django_blog.save() # django_blog.pk == 


鉴于 继承 的 运作 方式 ， 必 须 把 pk 和 id 都 设 为 None: 


>>> django_blog.pk = None 
>>> django_blog.id = None 
>>> django_blog.save() # django_blog.pk == 


这 个 过 程 不 会 复制 关联 的 对 象 。 如 果 想 复制 关系 ， 要 多 写 一 些 代码 。 在 下 述 示 例 中 ，Entry 与 Author 之 间 是 
多 对 多 关系 : 

>>> entry = Entry.objects.all()[0] # 某 篇 文章 

>>> old_authors = entry.authors.all() 

>>> entry.pk = None 


>>> entry.save() 
>>> entry.authors = old_authors # 保存 新 的 多 对 多 关系 


B.8 一 次 更 新 多 个 对 象 
若 想 把 QuerySet 中 所 有 对 象 的 某 个 字段 设 为 相同 的 值 ， 可 以 使 用 update() 方法 。 例 如 : 


# 更 新 2007 年 发 布 的 文章 的 标题 
Entry.objects.filter(pub_date year=2007).update(headline='Everything is the same') 














这 个 方法 只 能 用 于 设 定 非 关系 字段 和 ForeignKey 字段 。 更 新 非 关 系 字段 时 ， 以 常量 形式 提供 新 值 。 更 新 For- 
eignKey 字段 时 ， 把 新 值 设 为 要 指向 的 那个 模型 实例 。 例 如 ;: 








>>> b = Blog.objects.get(pk=1) 


# 修改 每 个 “Entry” 对 象 ， 让 它 归 属 这 个 博客 
>>> Entry.objects.all().update(blog=b) 











update() 方法 立即 执行 ， 返 回 查询 匹配 的 行 数 (如果 某 些 行 已 经 是 要 更 新 的 值 了 ， 返 回 的 行 数 与 实际 更 新 的 
行 数 不 同 ) 。 


对 要 更 新 的 Queryset 唯 有 一 个 限制 : 只 能 访问 一 个 数据 库 表 ， 即 模型 的 主 表 。 可 以 通过 关联 的 字段 过 滤 ， 但 
是 只 能 更 新 模型 主 表 中 的 列 。 例 如 : 

















>>> b = Blog.objects.get(pk=1) 


# 更 新 这 个 博客 中 所 有 文章 的 标题 
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>>> Entry.objects.select_related().filter(blog=b).update(headline='Everything is the same') 


注意 ，update() 方法 直接 转换 成 SQL 语句 。 直 接 更 新 执行 的 是 批量 操作 。update() 方法 不 会 在 模型 上 调用 
save() 方法 ， 也 不 会 发 送 pre_save 或 post_save 信号 (调用 save() 时 会 发 送 ) ， 更 不 会 更 新 设 定 了 au- 
to_now 选项 的 字段 。 如 果 想 保存 Queryset 中 的 各 个 对 象 ， 确 保 在 各 个 模型 实例 上 调用 save() 方法 ， 无 需 使 
用 特殊 的 函数 处 理 ， 执 行 迭代 查询 集合 ， 然 后 调用 save() 方法 : 






























































for item in my_queryset: 
item.save() 


























update() 调用 也 可 以 使 用 F 表达 式 ， 根 据 同一 个 模型 中 另 一 个 字段 的 值 更 新 字段 。 根 据 当前 值 递增 计数 器 时 
就 可 以 这 么 做 。 例 如 ， 下 述 代码 递增 博客 中 每 篇 文章 的 pingback 数量 : 

















>>> Entry.objects.all().update(n_pingbacks=F('n_pingbacks') + 1) 














然而 ,与 filter() 和 exclude() 不 同 ，update() 中 的 F() 对 象 不 能 涉及 联结 查询 ， 只 能 引用 要 更 新 那个 模型 
实例 中 的 字段 。 如 果 尝 试 通过 F() 对 象 引 入 联结 查询 ， 将 抛 出 FieldError: 
































# 抛 出 FieldError 
>>> Entry.objects.update(headline=F('blog name')) 


B.9 关联 的 对 象 


包含 关系 (ForeignKey、OneToOneField 或 ManyToManyField) 的 模型 实例 可 以 通过 便利 的 API 访问 关联 的 对 
象 。 


以 开头 的 模型 为 例 ，Entry 对 象 。 可 以 通过 访问 blog 属性 获取 关联 的 Blog 对 象 : e.blog。 




















(这 个 功能 在 背后 使 用 Python 描述 符 实现 。 你 无 须 关 注 内 部 细节 ， 我 指出 来 是 为 了 满足 你 的 好 奇 心 。) 























Django 还 为 关系 的 另 一 端 (被 关联 的 模型 到 定义 关系 的 模型 之 间 的 链接 ) 提供 了 存 取 API。 例 如 ，Blog 对 象 
b 可 以 通过 entry_set 属性 访问 所 有 关联 的 Entry 对 象 : b.entry_set.all()。 


本 节 的 所 有 示例 都 基 











于 开头 的 Blog、Author 和 Entry 模型 。 


B.9.1 一 对 多 关系 


正 向 





如 果 模 型 中 有 ForeignKey， 它 的 实例 可 以 通过 一 个 简单 的 属性 访问 关联 的 (外 部 ) 对 象 。 例 如 : 











>>> e = Entry.objects.get(id=2) 
>>> e.blog # 返回 关联 的 Blog 对 象 





通过 外 键 属性 还 可 以 获取 并 设 定 关 联 的 对 象 。 与 你 所 想 的 一 样 ， 除 非 调用 save() 方法 ， 否 则 外 键 不 会 存 和 人数 
据 库 。 例 如 : 


>>> e = Entry.objects.get(id=2) 
>>> e.blog = some_blog 
>>> e.save() 





如 果 外 键 设 定 了 nuLL=True 〈 即 允许 NULL 值 ) ， 可 以 把 值 设 为 None， 移 除 关系 。 例 如 : 





>>> e = Entry.objects.get(id=2) 
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>>> e.blog = None 
>>> e.Save() # "UPDATE blog_entry SET blog id = NULL ...;" 


首次 访问 关联 的 对 象 时 ， 正 向 一 对 多 关系 会 缓存 起 来 。 后 续 在 相同 的 对 象 上 访问 外 键 都 读 取 缓 存 。 例 如 : 


>>> e = Entry.objects.get(id=2) 
>>> print(e.blog) # 访问 数据 库 ， 检 索 关联 的 Blog 对 象 
>>> print(e.blog) # 不 访问 数据 库 ， 使 用 缓存 





注意 ，QuerySet 的 select_related() 方法 会 事先 递归 重新 填充 所 有 一 对 多 关系 的 缓存 。 例 如 : 


反 向 





>>> e = Entry.objects.select_related().get(id=2) 
>>> print(e.blog) # 不 访问 数据 库 ， 使 用 缓存 
>>> print(e.bLog) # 不 访问 数据 库 ， 使 用 缓存 














如 果 一 个 模型 中 有 外 键 ， 外 键 指向 的 那个 模型 能 通过 一 个 Manager 获取 外 键 所 在 模型 的 全 部 实例 。 默 认 情 况 
下 ， 这 个 Manager 名 为 foo_set， 其 中 foo 是 源 模型 名 称 的 小 写 形式 。 这 个 Manager 返回 QuerySet， 可 以 像 
B.3 节 所 述 那样 过 滤 和 处 理 。 


例如 : 











>>> b = Blog.objects.get(id=1) 
>>> b.entry_set.all() # 返回 与 b 关联 的 所 有 Entry 对 象 


# b.entry_set 是 一 个 Manager， 返回 QuerySet 
>>> b.entry_set.filter(headline_ contains='Lennon') 
>>> b.entry_set.count() 


定义 ForeignKey 时 可 以 通过 related_name 参数 覆盖 foo_set 的 名 称 。 假 如 把 Entry 模型 中 的 外 键 字段 改 成 
blog = ForetignKey(BLog，retLated_name='entries')， 那 么 上 述 示例 代码 就 变 成 了 : 





>>> b = Blog.objects.get(id=1) 
>>> b.entries.all() # 返回 与 b 关联 的 所 有 Entry 对 象 


# b.entries 是 一 个 Manager， 返 回 QuerySet 
>>> b.entries.filter(headline__contains='Lennon') 
>>> b.entries.count() 


使 用 自 定义 的 反 向 管理 器 



































默认 情况 下 ， 反 向 关系 使 用 的 RelatedManager 是 那个 模型 默认 管理 器 的 子 类 。 如 果 想 让 特定 查询 使 用 不 同 的 














管理 器 ， 可 以 使 用 下 述 句法 : 


from django.db import models 


class Entry(models.Model): 
和 
objects = models.Manager() # 默认 管理 器 
entries = EntryManager() # 自 定义 管理 器 


b = Blog.objects.get(id=1) 
b.entry_set(manager='entries').all() 
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如 果 EntryManager 的 get_queryset() 方法 执行 了 默认 的 过 滤 操 作 ， 会 应 用 到 aLL() 调用 上 。 





当然 ， 指 定 自 定义 的 反 向 管理 器 后 还 可 以 调用 其 中 定义 的 方法 : 











b.entry_set(manager='entries').is_published() 


处 理 关 联 对 象 的 其 他 方法 


除了 B.3 节 所 述 的 Queryset 方法 之 外 ， 外 键 的 管理 器 还 提供 了 用 于 处 理 关联 对 象 集合 的 其 他 方法 。 各 方法 的 
概述 如 下 (详情 参见 文档 ) 。 











。 add(obj1，obj2，..): 把 指定 模型 对 象 添加 到 关联 的 对 和 象 集合 中 。 

。 create(**kwargs): 新 建 对 象 ， 保 存 之 后 放 入 关联 的 对 象 集 合 中 。 返 回 新 建 的 对 象 。 
。 remove(obj1，obj2,..): 从 关联 的 对 象 集合 中 删除 指定 的 模型 对 象 。 

。 clear(): 删除 所 有 关联 的 对 象 。 

。 set(objs): 替换 关联 的 对 象 集合 。 









































若 想 一 次 赋值 多 个 关联 的 对 象 ， 只 需 把 关联 的 对 象 放 和 人 任何 可 迁 代 的 对 象 。 可 迁 代 的 对 象 可 以 包含 对 象 实 
例 ， 也 可 以 列 出 主键 的 值 。 例 如 : 








b = Blog.objects.get(id=1) 
b.entry_set = [el1，e2] 


这 里 ，el 和 e2 可 以 是 完整 的 Entry 实例 ， 也 可 以 是 主键 的 值 。 





如 果 clear() 可 用 ， 先 把 entry_set 中 现 有 的 对 象 全 部 删除 ， 然 后 再 添加 可 迄 代 对 象 《上 例 中 是 一 个 列表 ) 
中 的 对 象 。 如 果 clear() 方法 不 可 用 ， 在 现 有 对 象 的 基础 上 添加 可 迭代 对 象 中 的 对 象 。 


本 节 所 述 的 反 向 操作 都 直接 影响 数据 库 中 的 数据 。 添 加 、 新 建 和 删除 都 立即 自动 存 信 数据库。 
























































B.9.2 多 对 多 关系 
多 对 多 关系 的 两 端 都 有 相互 访问 的 API， 使 用 方法 与 上 述 反 向 一 对 多 关系 一 样 。 











唯一 的 区 别 是 属性 的 命名 : 定义 ManyToManyField 的 模型 使 用 的 属性 名 与 字段 本 身 相 同 ， 而 反 向 模型 使 用 源 
模型 的 小 写 名 称 ， 后 加 '_set' (与 反 向 一 对 多 关系 一 样 ) 。 


为 了 便于 理解 ， 下 面 举 个 例子 : 








>>> e = Entry.objects.get(id=3) 

>>> e.authors.all() # 返回 这 个 Entry 对 象 的 所 有 Author 对 象 
>>> e.authors.count() 

>>> e.authors.filter(name__contains='John') 

>>> a = Author.objects.get(id=5) 

>>> a.entry_set.all() # 返回 这 个 Author 对 象 的 所 有 Entry 对 象 





与 ForetgnKey 一 样 ，ManyToManyField 也 可 以 指定 reLated_name。 在 上 述 示例 中 ， 如 果 Entry 模型 中 的 Many- 
ToManyField 指定 了 retLated_name='entries' ， 那 么 每 个 Author 实例 都 有 entries 属性 ， 而 非 entry_set。 








B.9.3 一 对 一 关系 








对 一 关系 与 多 对 一 关系 很 像 。 如 果 模 型 中 有 0neTo0neFieLd， 模 型 的 实例 可 以 通过 模型 上 的 一 个 简单 属性 访 
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问 关联 的 对 象 。 
例如 : 


class EntryDetail(models.Model): 
entry = models.OneToOneField(Entry) 
details = models.TextField() 


ed = EntryDetail.objects .get(id=2) 
ed.entry # 返回 关联 的 Entry 对 象 





区 别 在 于 反 向 查询 。 一 对 一 关系 中 关联 的 模型 也 有 一 个 Manager， 但 是 它 表 示 一 个 对 象 ， 而 不 是 对 象 集合 : 


e = Entry.objects.get(id=2) 
e.entrydetail # 返回 关联 的 EntryDetail 对 象 


如 果 没 有 关联 的 对 象 ，Django 抛 出 DoesNotExist 异常 。 
为 反 向 关系 赋值 的 方式 与 赋值 正 向 关系 一 样 : 





e.entrydetail = ed 


B.9.4 通过 关联 的 对 象 查询 


涉及 关联 对 象 的 查询 ， 其 规则 与 按 字 段 查询 一 样 。 指 定 查询 条 件 时 ， 可 以 使 用 关联 对 象 实例 自身 ， 也 可 以 使 
用 关联 对 象 的 主键 值 。 


假如 一 个 Blog 对 象 b 的 id 为 5， 下 述 三 个 查询 是 等 效 的 : 












































Entry.objects.filter(blog=b) # 使 用 对 象 实例 查询 
Entry.objects.filter(blog=b.id) # 使 用 实例 的 id 查询 
Entry.objects.filter(blog=5) # 直接 使 用 id 


B.10 回落 到 原始 SQL 


如 果 发 现 查询 太 复 杂 ，Django 的 数据 库 映 射 器 无 法 处 理 ， 可 以 退 一 步 ， 自 己 动手 编写 SQL 。 


最 后 ， 值 得 指出 的 一 点 是 ，Django 的 数据 库 层 只 是 数据 库 的 接口 。 你 可 以 通过 其 他 工具 、 编 程 语言 或 数据 库 
框架 访问 数据 库 ，Django 应 用 程序 的 数据 库 并 不 是 Django 专用 的 。 
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第 10 章 对 通用 视图 做 了 介绍 ， 但 是 没 涉及 很 多 本 
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的 选项 。 为 了 能 够 理解 这 里 的 内 容 ， 请 先 阅读 第 10 音 。 在 阅读 的 过 程 
Publisher 和 Author 模型 是 如 何 定 义 的 。 这 篇 附录 中 的 示例 会 用 到 那 

















可 能 需要 导 





外 要 的 细节 。 这 篇 附录 说 明 各 个 通用 视图 ， 并 简 述 各 视图 可 用 
回 那 一 章 ， 回 顾 Book、 














个 模型 。 如 与 











想 继续 深入 了 解 通用 视 


图 的 高 级 话题 【例如 在 基于 类 的 视图 中 使 用 混入 (mixin) ) ， 请 访问 Django Project 网 站 。 














C.1 通用 视图 的 通用 参数 


多 数 通 用 视图 接受 大 量 参 数 ， 用 于 修改 视图 的 行为 。 其 中 部 分 参数 在 不 同 视图 中 的 作用 是 一 样 的 。 表 C-1 说 




















明 各 个 通用 参数 。 不 管用 在 哪个 通用 视图 中 ， 

















这 些 参数 的 作用 与 下 表 所 述 的 一 样 。 





表 C-1: 通用 视图 的 通用 参数 








参数 说 明 





布尔 值 ， 指 明 没有 对 象 时 是 否 显示 页 首 


allow_empty 






































可 用 ， 视 图 抛 











1。 设 为 FaLse 昌 
上 404 错误 ， 而 不 显示 空 页面 。 默 认为 














寸 ， 如 果 没 有 对 象 


True。 


应 用 到 视图 模板 上 额外 的 模板 上 下 文 处 理 器 列表 〈 除 默认 的 处 理 器 之 








context_processors 


一 个 空 曲 
extra_context | 了 


外 ) 。 参 见 第 8 章 。 


包含 添加 到 模板 上 下 文中 的 值 。 默 认为 




















4 


I 


mimetype 


典 中 的 值 是 可 调用 对 象 ， 通 用 视 


定 所 得 文档 的 MIME 类 型 。 默 认为 DEFAULT_MIME_TYPE 设置 的 值 ， 如 
果 没 修改 的 话 ， 是 text/html。 


























个 空 字典 。 如 果 字 
图 在 泻 染 模板 前 调用 它 。 








从 中 读 取 对 象 的 一 个 QuerySet (如 Author.objects.all()) 。QuerySet 


queryset 





template_loader 
时 。 


的 说 明 参 见 附 录 B。 多 数 通 
用 于 加 载 模板 的 模板 加 载 器 。 默 认为 django.template.loader。 参 见 第 8 



































j 视 图 需要 这 个 参数 。 








渔 染 页 面 所 用 模板 的 完整 名 称 。 可 用 于 履 盖 从 Queryset 中 推导 出 的 默认 


tempLate_name 


模板 名 称 。 








tempLate_object_name 象 的 视 医 
值 的 后 面 力 











在 模板 上 下 文中 使 
(如 object_list 视图 和 各 个 基于 日 期 的 视图 
































I 上 '_ List'。 














的 模板 变量 的 名 称 。 默 认为 'object' 。 列 出 多 个 对 


) 将 在 这 个 参数 





C.2 简单 的 通用 视图 








django.views.generic.base 模块 中 有 几 个 简 身 





的 视图 ， 针 对 几 个 常见 的 使 








板 和 重 定向 。 




















] 场景 $ 











演 染 不 需要 视图 逻辑 的 模 
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C.2.1 演 染 模板 一 一 TempLateView 
这 个 视图 把 从 URL 中 捕获 的 关键 字 参 数 通 过 上 下 文 传 给 模板 ， 演 染指 定 的 模板 。 
以 下 述 URL 配置 为 例 : 








from django.conf.urls import url 
from myapp.Vviews import HomePageView 


urlpatterns = [ 
url(r'^$', HomePageView.as_view(), name='home'), 


] 
对 于 下 面 这 个 简单 的 views.py 来 说 ， 演 染 的 是 home.html 模板 ， 返 回 一 个 列表 ， 列 出 前 5 篇 文章 : 

















from django.views.generic.base import TemplateView 
from articles.models import Article 


class HomePageView(TemplateView): 
template_name = "home.html" 
def get context data(self, **kwargs): 
context = super(HomepPageView, self).get_ context_data(**kwargs) 


context['latest articles'] = Article.objects.all()[:5] 
return context # 请 求 `/、 


C.2.2 重 定向 到 其 他 URL 


django.views.generic.base.RedirectView() 重 定 向 到 指定 URL。 




















指定 的 URL 中 可 能 包含 字典 形式 的 格式 字符 串 ， 这 些 格式 字符 串 会 使 用 从 URL 中 捕获 的 参数 代 换 掉 。 这 一 
步 始终 执行 《即使 没有 参数 传人 ) ， 因 此 URL 中 的 % 必须 写成 %%， 这 样 在 输出 时 Python 才 会 将 其 转换 成 
一 个 百 分 号 。 





如 果 指 定 的 URL 是 None，Django 返回 HttpResponseGone (410) 。 
示例 views.py: 


from django.shortcuts import get_object_or_404 
from django.views.generic.base import RedirectView 


from articles.models import Article 
class ArticleCounterRedirectView(RedirectView): 


permanent = False 
query_string = True 
pattern_name = 'article-detail' 


def get_redirect url(self, *args, **kwargs): 
article = get _ object or_404(Article, pk=kwargs['pk']) 
article.update counter() 
return super(ArticleCounterRedirectView, 
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self).get redirect url(*args, **kwargs) 
示例 urls.py: 


from django.conf.urls import url 
from django.views.generic.base import RedirectView 


from article.views import ArticleCounterRedirectView, ArticleDetail 


urlpatterns = [ 

url(r'^counter/(?P<pk>[0-9]+)/$', 
ArticleCounterRedirectView.as_view(), 
name='articLe-counter ' ) ， 

url(r'^details/(?P<pk>[0-9]+)/$', 
ArticleDetail.as_view(), 
name='"article-detail'), 

url(r'^go-to-django/s$', 
RedirectView.as_view(url='http://djangoproject.com'), 
name='go-to-django' )， 


url 





重 定向 的 目标 URL， 一 个 字符 串 。 为 None 时 抛 出 HTTP 410 错误 。 


pattern_name 


重 定向 的 模板 URL 模式 名 称 。 反 向 解析 的 方式 与 在 视图 中 传人 *args 和 **kwargs 时 一 样 。 





permanent 


指定 是 否 永久 重 定向 。 唯 一 的 区 别 是 返回 的 HITP 状态 码 。 设 为 True 时 ， 习 
False 时 ， 重 定向 使 用 状态 码 302。 默 认为 True。 


mm 


定向 使 用 状态 码 301; 设 为 








query_string 





是 否 把 GET 查询 字符 串 传 给 新 URL。 设 为 True 时 ， 查 询 字 符 串 追加 到 URL 末尾 ;， 设 为 False 时 ， 丢 掉 查 询 
字符 串 。 默 认为 False。 





方法 
get_redirect_url(*args，**kwargs) 用 于 构建 重 定向 的 目标 URL。 


默认 的 实现 以 url 为 基础 ， 然 后 代 换 % 标记 的 具名 参数 ， 变 成 URL 中 具名 分 组 捕获 的 字符 串 。 





















































如 果 未 传人 urL，get_redirect_urtL() 尝试 使 用 从 URL 中 捕获 的 信息 (具名 分 组 和 匿名 分 组 都 用 上 ) 反 向 解 
析 pattern_name。 








如 果 把 query_string 设 为 True， 还 会 在 生成 的 URL 末尾 加 上 查询 字符 串 。 
子 类 可 以 根据 需要 实现 所 需 的 行为 ， 只 要 返回 一 个 可 以 重 定 向 的 URL 字符 串 即 可 。 
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C.3 列表 /详情 通用 视图 








列表 /详情 通用 视图 针对 的 常见 使 用 场景 是 ， 在 一 个 视图 中 列 出 一 些 元 素 ， 然 后 在 单独 的 视 
详情 。 





C.3.1 列 出 对 象 
django.views.generic. list.ListView 


这 个 视图 显示 的 页 面 中 列 出 一 系列 对 象 。 





示例 views .py : 


from django.views.generic.list import ListView 
from django.utils import timezone 


from articles.models import Article 
class ArticleListView(ListView): 
model = Article 


def get context data(self, **kwargs): 
context = super(ArticleListView, self).get context_data(**kwargs) 
context[ 'now'] = timezone.now() 
return context 


示例 myapp/urls.py: 


from django.conf.urls import url 
from article.views import ArticleListView 


urlpatterns = [ 
url(r'^$', ArticleListView.as_view(), name='article-list'), 


] 
示例 myapp/article_list.html: 


<h1>Artictes</h1> 
<UL> 
{% for article in object_ list %} 
<li>{{ articte.pub_ dateldate }} - {{ article.headline }}</li> 
{% empty %} 
<li>No articles yet.</li> 
{% endfor %} 
</ul> 


C.3.2 详情 视图 


django.views.generic.detail.DetailView 











这 个 视图 显示 单个 对 象 的 详情 。 























PF 显示 各 元 素 的 
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示例 myapp/views.py: 


from django.views.generic.detail import DetailView 
from django.utils import timezone 


from articles.models import Article 
class ArticleDetailView(DetailView): 
model = Article 


def get context data(self, **kwargs): 
context = super(ArticleDetailView, 
self).get_context_data(**kwargs) 
context[ ' now'] = timezone.now() 
return context 


示例 myapp/urls.py: 


from django.conf.urls import url 
from article.views import ArticleDetailView 


urlpatterns = [ 
url(r'^(?P<slug>[-_\w]+)/$', 
ArticleDetailView.as_view(), 
name='"article-detail'), 


] 
示例 myapp/article_detail.html: 


<h1>{{ object.headline }}</h1> 

<p>{{ object.content }}</p> 

<p>Reporter: {{ object.reporter }}</p> 
<p>Published: {{ object.pub_datel|date }}</p> 
<p>Date: {{ now|date }}</p> 


C.4 基于 日 期 的 通用 视图 





























django.views.generic.dates 模块 中 基于 日 期 的 通用 视图 用 于 显示 基于 日 期 的 层次 数据 。 














| 


C.4.1 ArchiveIndexView 








顶层 索引 页 面 ， 显 示 最 新 的 对 象 按 日 期 排序 ) 。 如 果 未 把 allow_future 设 为 True， 未 来 日 期 对 应 的 对 象 不 
包含 在 内 。 














十 下 玉 


除了 django.views.generic.list.MultipleObjectMixin (混入 django.views.generic.dates.BaseDateListView 


中 ) 提供 的 上 下 文 之 外 ， 还 有 : 


。 date_list: 一 个 DateQuerySet 对 象 ， 包 含 根据 queryset 判断 具有 对 象 的 所 有 年 份 (以 date- 
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time.datetime 对 象 表示 ) ， 倒 序 排列 。 





。 context_object_name 的 默认 值 为 Latest。 


。 template_name_suffix 的 默认 值 为 _archive。 


























。 默认 提供 的 date_list 按 年 划分 ， 不 过 可 以 通过 date_list_period 属性 调整 为 按 月 或 按 于 


也 是 这 样 。 
示例 myapp/urls.py: 


from django.conf.urls import url 


from django.views.generic.dates import ArchiveIndexView 
from myapp.models import Article 


urlpatterns = [ 
url(r'^archive/$', 
ArchiveIndexView.as_view(model=Article, date field="pub_date"), 
name="article_archive"), 


] 
示例 myapp/article_archive.html: 


<ul> 
{% for article in Latest %} 
<li>{{ article.pub_date }}: {{ article.title }}</li> 
{% endfor %} 
</ul> 





上 述 模 板 输出 所 有 文章 。 











C.4.2 YearArchiveView 





























划分 。 子 类 


按 月 归档 页 面 ， 显 示 指 定年 份 中 的 所 有 月 份 。 如 果 未 把 allow_future 设 为 True， 未 来 日 期 对 应 的 对 象 不 包含 


在 内 。 


在 平 驻 


除了 django.views.generic.list.MultipleObjectMixin (混入 django.views.generic.dates.BaseDateListView 


中 ) 提供 的 上 下 文 之 外 ， 还 














。 date_list: 一 个 DateQuerySet 对 象 ， 包 含 根据 queryset 判断 具有 对 象 的 所 有 月 份 (以 date- 


time.datetime 对 和 象 表示 ) ， 升 序 排列 。 
。 year: 一 个 date 对 象 ， 表 示 指 定 的 年 。 


。 next_year: 一 个 date 对 象 ， 表 示 由 aLLow_empty 和 aLLow_future 确定 的 下 


TT 








py 











F 的 第 

















天 。 














。 previous_year: 一 个 date 对 象 ， 表 示 由 allow_empty 和 allow_future 确定 的 前 一 年 的 第 一 天 。 








。 template_name_suffix 的 默认 值 为 _archive_year。 
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示例 myapp/views.py: 


from django.views.generic.dates import YearArchiveView 
from myapp.models import Article 


class ArticleYearArchiveView(YearArchiveView): 
queryset = Article.objects.all() 
date_field = "pub_date" 
make_object_list = True 
allow_future = True 


示例 myapp/urls.py: 


from django.conf.urls import url 
from myapp.views import ArticleYearArchiveView 


urlpatterns = [ 
url(r'^(?P<year>[0-9]{4})/$', 
ArticleYearArchiveView.as_view(), 
name="article year_archive"), 


] 
示例 myapp/article_archive_year.html: 


<ul> 
{% for date in date_ list %} 
<li>{{ datel|date }}</li> 
{% endfor %} 
</ul> 
<div> 
<h1>ALL Articles for {{ year|ldate:"Y" }}</h1i> 
{% for obj in object_list %} 
<p> 
{{ obj.title }} - {{ obj.pub_ dateldate:"F j, Y"” }} 
</p> 
{% endfor %} 
</div> 


C.4.3 MonthArchiveView 





按 月 归档 页 面 ， 显 示 指 定 月 份 中 的 所 有 对 象 。 如 果 未 把 aLLow_future 设 为 Trrue， 未 来 日 期 对 应 的 对 象 不 包含 
在 内 。 








下 下 交 
除了 Multiple0bjectMixin (混和 人 BaseDateListView 中 ) 提供 的 上 下 文 之 外 ， 还 有 : 


。 date_list: 一 个 DateQuerySet 对 象 ， 包 含 根据 queryset 判断 的 一 月 之 中 具有 对 象 的 所 有 日 (以 date- 
time.datetime 对 象 表示 ) ， 升 序 排列 。 


。 month: 一 个 date 对 象 ， 表 示 指 定 的 月 。 
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。 next_month; 一 个 date 对 象 ， 表 示 由 aLLow_empty 和 aLLow_future 确定 的 下 一 月 的 第 一 天 。 
。 previous_month:; 一 个 date 对 象 ， 表 示 由 aLLow_empty 和 aLLow_future 确定 的 前 一 月 的 第 一 天 。 


注意 





。 template_name_suffix 的 默认 值 为 _archive_month。 


示例 myapp/views.py: 


from django.views.generic.dates import MonthArchiveView 
from myapp.models import Article 


class ArticleMonthArchiveView(MonthArchiveView): 
queryset = Article.objects.all() 
date_field = "pub_date" 
make_object_list = True 
allow_ future = True 


示例 myapp/urls.py: 


from django.conf.urls import url 
from myapp.views import ArticleMonthArchiveView 


urlpatterns = [ 

# 比如 /2012/aug/ 

url(r'^(?P<year>[0-9]{4})/(?P<month>[-\w]+)/$', 
ArticleMonthArchiveView.as_view(), 
name="archive_month"), 

# 比如 /2012/08/ 

url(r'^(?P<year>[0-9]{4})/(?P<month>[0-9]+)/$', 
ArticleMonthArchiveView.as_view(month_format="'%m' ) ， 
name="archive_month_numeric"), 


] 
示例 myapp/article_archive_month.html: 


<ul> 
{% for article in object _ list %} 
<li>{{ article.pub_datel|date:"F j, Y" }}: 
{{ article.title }} 
</li> 
{% endfor %} 
</ul> 


<p> 
{% if previous_month %} 
Previous Month: {{ previous_ month|date:"F Y"” }} 
{% endif %} 
{% if next_month %} 
Next Month: {{ next_month|date:"F Y" }} 
{% endif %} 
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</p> 


C.4.4 WeekArchiveView 





按 周 归 档 页 面 ， 显 示 指 定 周 中 的 所 有 对 象 。 如 果 未 把 aLLow_future 设 为 True， 未 来 日 期 对 应 的 对 象 不 包含 在 
内 。 











上 下 文 


除了 Multiple0bjectMixin (混入 BaseDateListView 中 ) 提供 的 上 下 文 之 外 ， 还 有 : 





。 week: 一 个 date 对 象 ， 表 示 指 定 周 的 第 一 天 。 
。 next_week: 一 个 date 对 象 ， 表 示 由 aLLow_empty 和 aLLow_future 确定 的 下 一 周 的 第 一 天 。 
。 previous_week: 一 个 date 对 象 ， 表 示 由 aLLow_empty 和 aLLow_future 确定 的 前 一 周 的 第 一 天 。 






































生意 





。 template_name_suffix 的 默认 值 为 _archive_week。 


示例 myapp/views .py: 


from django.views.generic.dates import WeekArchiveView 
from myapp.models import Article 


class ArticleWeekArchiveView(WeekArchiveView): 
queryset = Article.objects.all() 
date_field = "pub_date" 
make_object_list = True 
week_format = "%W" 
allow_future = True 


示例 myapp/urls.py: 


from django.conf.urls import url 
from myapp.views import ArticleWeekArchiveView 


urlpatterns = [ 
# 比如 /2012/week/23/ 
url(r'^(?P<year>[0-9]{4})/week/(?P<week>[0-9]+)/$', 
ArticleWeekArchiveView.as_view(), 
name="archive_week"), 


] 
示例 myapp/article_archive week.htnml: 


<hi>Week {{ week|date:'W' }}</h1> 


<ul> 
{% for article in object_list %} 
<li>{{ article.pub_date|date:"F j, Y" }}: {{ 
article.title }}</li> 
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{% endfor %} 
</ul> 


<p> 
{% if previous_week %} 
Previous Week: {{ previouys week|date:"F Y" }} 
{% endif %} 
{% if previous_ week and next week %}--{% endif %} 
{% if next_ week %} 
Next week: {{ next_week|date:"F Y" }} 
{% endif %} 
</p> 




















这 个 示例 输出 了 周 几 。WeekArchiveView 中 ，week_format 默认 采用 的 格式 是 "%U"， 这 是 美国 使 用 的 格式 ， 一 
周 从 周 日 开始 。"%W" 则 使 用 ISO 格式 ,一 周 从 周一 开始 。"%wW" 在 strftime() 和 date 中 的 作用 与 此 相同 。 














然而 ，date 模板 过 滤器 无 法 输出 美国 的 周 制 ，"%U" 输出 的 是 距 Unix 纪元 的 秒 数 。 














C.4.5 DayArchiveView 








按 日 归档 页 面 ， 显 示 指 定 一 天 中 的 所 有 对 象 。 如 果 未 把 aLLow_future 设 为 True， 不 管 未 来 的 日 期 有 没有 对 应 
的 对 象 ， 未 来 的 日 都 抛 出 404 错误 。 

















下属 





除了 Multiple0bjectMixin (混入 BaseDateListView 中 ) 提供 的 上 下 文 之 外 ， 还 有 : 





。 day: 一 个 date 对 象 ， 表 示 指 定 的 日 。 

。 next_day: 一 个 date 对 象 ， 表 示 由 allow_empty 和 aLLow_future 确定 的 下 一 天 。 

。 previous_day: 一 个 date 对 象 ， 表 示 由 aLLow_empty 和 atLLow_future 确定 的 前 一 天 。 

。 next_month: 一 个 date 对 象 ， 表 示 由 aLLow_empty 和 aLLow_future 确定 的 下 一 月 的 第 一 天 。 

。 previous_month: 一 个 date 对 象 ， 表 示 由 aLLow_empty 和 aLLow_future 确定 的 前 一 月 的 第 一 天 。 


























生意 





。 template_name_suffix 的 默认 值 为 archive_day。 


示例 myapp/views.py: 


from django.views.generic.dates import DayArchiveView 
from myapp.models import Article 


class ArticleDayArchiveView(DayArchiveView): 
queryset = Article.objects.all() 
date_field = "pub_date" 
make_object_list = True 
allow_future = True 


示例 myapp/urls.py: 


from django.conf.urls import url 
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from myapp.Views import ArticleDayArchiveView 


urlpatterns = [ 
# 比如 /2012/nov/10/ 
url(r'^(?P<year>[0-9]{4})/(?P<month>[-\w]+)/(?P<day>[0-9]+)/$', 
ArticleDayArchiveView.as_view(), 
name="archive_day'"), 


] 
示例 myapp/article_archive_day.html: 


<h1>{{ day }}</h1> 


<ul> 
{% for article in object list %} 
<li> 
{{ article.pub_date|date:"F j, Y" }}: {{ article.title }} 
</Li> 
{% endfor %} 
</ul> 
<p> 


{% if previous_day %} 
Previous Day: {{ previous day }} 
{% endif %} 
{% if previous_day and next_day %}--{% endif %} 
{% if next_day %} 
Next Day: {{ next_day }} 
{% endif %} 
</ ps 


C.4.6 TodayArchiveView 


按 日 归档 页 面 ， 显 示 今 天 的 所 有 对 象 。 作 用 与 django.views.generic.dates.DayArchiveView 完全 一 样 ， 只 
过 使 用 的 是 今天 的 日 期 ， 而 不 通过 year/month/day 参数 指定 。 


习 











Vy 


一 言 
六 有 尽 





。 template_name_suffix 的 默认 值 为 archive_today。 


示例 myapp/views.py: 


from django.views.generic.dates import TodayArchiveView 
from myapp.models import Article 


class ArticleTodayArchiveView(TodayArchiveView): 
queryset = Article.objects.all() 
date_field = "pub_date" 
make_object_list = True 
aLLow_future = True 
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示例 myapp/urls.py: 


from django.conf.urls import 


from myapp.views import Artic 


urlpatterns = [ 
url(r'^today/$', 
ArticLeTodayArchiveVi 
name="archive_today") 


] 





url 


leTodayArchiveView 


ew.as_view(), 


3 


怎么 不 给 出 TodayArchiveView 的 示例 模板 了 ? 





这 个 视图 默认 使 用 的 视图 与 DayArchiveView 一 样 ， 因 此 示例 同 前 。 如 果 想 使 














属性 设 为 新 模板 的 名 称 。 





C.4.7 DateDetailView 


























其 他 模板 ， 把 template_name 





呈现 单个 对 象 的 页 面 。 如 果 未 把 aLLow_future 设 为 True， 如 果 对 象 对 应 的 是 未 来 日 期 ， 默 认 抛 出 404 错误 。 


士 下 注 


。 在 DateDetailView 中 与 model 关联 的 那个 对 象 。 








。 template_name_suffix 的 默认 值 为 detail。 


示例 myapp/urls.py: 


from django.conf.urls import 


ur 


from django.views.generic.dates import DateDetailView 


urlpatterns = [ 


url(r'^(?P<year>[0-9]+)/(?P<month>[-\w]+)/(?P<day>[0-9]+)/ 


(?P<pk>[0-9]+)/$', 


DateDetailView.as_view(model=Article, date field="pub_date"), 


name="archive_date_de 


] 
示例 myapp/article_detail.htnml: 


<h1>{{ object.title }}</h1> 


kt )5 


C.5 在 基于 类 的 视图 中 处 理 表单 





处 理 表 单 时 要 考虑 3 种 情况 : 








。 原来 的 GET (为 空 ， 或 预 填 的 








表单 ) 








。 POST 发 送 无 效 的 数据 (通常 








了 次 显示 表单 ， 并 指 
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。 POST 发 送 有 效 的 数据 (通常 在 处 理 数据 之 后 重 定向 ) 











自己 处 理 这 些 情 况 往往 要 重复 编写 大 
视图 ， 用 于 处 理 表单 。 





名 





样板 代码 (参见 文档 ) 。 鉴 于 此 ，Django 提供 了 一 系列 基于 类 的 通用 








C.5.1 简单 的 表单 


以 下 面 这 个 简 








lm 























的 联系 表单 为 何 ， 


# forms .py 
from django import forms 


class ContactForm(forms .Form) : 
name = forms.CharField() 
message = forms.CharField(widget=forms.Textarea) 


def send_email(self): 


# 发 送 邮 件 时 使 用 self.cleaned_data 字典 中 的 数据 
pass 


对 应 的 视图 可 以 使 用 FormView 构建 : 


# views.py 


from myapp.forms import ContactForm 


from django.views.generic.edit import FormView 


class ContactView(FormView): 
tempLate_name = 'contact.html' 
form_cLass = ContactForm 
success_url = '/thanks/' 


def form valid(self, form): 
# 收 到 有 效 的 表单 数据 时 调用 这 个 方法 
# 应 该 返回 一 个 HttpResponse 对 象 
form.send_email() 


return super(ContactView, self).form valid(form) 


活 
ul 


FormView 继承 TemplateResponseMixin， 因 此 这 里 可 以 使 用 tempLate_name。 
。 form_valid() 的 默认 实现 只 是 重 定 向 到 success_url。 








C.5.2 模型 表单 





















































处 理 模 型 时 使 用 通用 视图 非常 方便 。 只 要 能 确定 模型 类 ， 通 用 视图 就 能 自动 创建 一 个 ModelForm。 确 定 
类 的 方法 如 下 : 

















。 使 用 model 属性 指定 的 模型 类 。 
。 使 用 get_object() 返回 的 对 象 所 属 的 类 。 
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。 使 用 queryset 对 应 的 模型 。 





模型 表单 视图 提供 的 form_valid() 能 自动 保存 模型 。 如 果 有 其 他 需求 ， 可 以 覆盖 这 个 方法 。 下 文 有 示例 。 


无 需 为 CreateView 或 UpdateView 提供 success_urL， 目 标 地 址 可 以 使 用 模型 对 象 的 get_absoLute_urtL() 方法 
获取 。 


如 果 想 使 用 自 定义 的 ModelForm (例如 添加 额外 的 数据 验证 ) ， 只 需 在 视图 中 设 定 form_class。 


指定 自 定义 的 表单 类 时 ， 即 便 form_class 可 能 是 ModelForn 的 子 类 ， 仍 要 指定 模型 。 


首先 ， 在 Author 类 中 添加 get_absolute_ur1(): 





# models.py 


from django.core.urlresolvers import reverse 
from django.db import models 


class Author(models.Model): 
name = models.CharField(max_length=200) 


def get absolute url(self): 
return reverse('author-detail', kwargs={'pk': self.pk}) 


然后 就 可 以 把 具体 的 工作 交 给 CreateView 等 视图 去 做 了 。 注 意 基 于 类 的 通用 视图 是 如 何 找 到 的 ， 自 己 不 用 写 
任何 逻辑 。 


# ViLews .py 


from django.views.generic.edit import CreateView, UpdateView, DeleteView 
from django.core.urlresolvers import reverse_Lazy 
from myapp.models import Author 


class AuthorCreate(CreateView): 
model = Author 
fields = ['name'] 


class AuthorUpdate(UpdateView): 
model = Author 
fields = ['name'] 


class AuthorDelete(DeleteView): 
model = Author 
SUCCess_UrL = reverse lazy('author-list') 


这 里 要 使 用 reverse_Lazy()， 不 能 使 用 reverse()， 因 为 导入 文件 时 URL 尚未 加 载 。 


fields 属性 的 作用 与 ModelForn 内 部 Meta 类 的 fields 属性 一 样 。 正 常情 况 下 ， 这 个 属性 是 必须 的 ， 否 则 视 
图 会 抛 出 ImproperlyConfigured 异常 。 








如 果 同 时 指定 fields 和 form_class 属性 ， 也 会 抛 出 ImproperLyConfigured 异常 。 
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最 后 ， 在 URL 配置 中 使 用 这 些 新 视图 : 


# urls.py 


from django.conf.urls import url 
from myapp.views import AuthorCreate, AuthorUpdate, AuthorDelete 


urlpatterns = [ 
# ... 
url(r'author/add/$', AuthorCreate.as_view(), name='author_add'), 
url(r'author/(?P<pk>[0-9]+)/$', AuthorUpdate.as_view(), 
name='author_Update ' ) ， 
url(r'author/(?P<pk>[0-9]+)/delete/$', AuthorDelete.as_view(), 
name='author_delete'), 


] 


在 这 个 示例 中 : 


。 CreateView 和 UpdateView 使 用 myapp/author_form.html 


。 DeleteView 使 用 myapp/author_confirm delete.html 


如 果 想 让 CreateView 和 UpdateView 使 用 不 同 的 模板 ， 在 视图 类 中 设 定 template_name 或 template_name_suf- 
fix, 


C.5.3 模型 和 request.user 




















使 用 CreateView 创建 对 象 时 ， 若 想 记 录 是 哪个 用 户 创建 的 ， 可 以 使 用 自 定义 的 ModelForm。 首 先 ， 在 模型 中 
添加 外 键 关系 : 








# models.py 


from django.contrib.auth.models import User 
from django.db import models 


class Author(models.Model): 
name = models.CharField(max_length=200) 


created_by = models.ForeignKey(User) 


:ee 





























在 视图 中 要 确保 可 编辑 的 字段 列表 中 没有 created_by， 然 后 覆盖 form_valid()， 添 加 用 户 : 























from django.views.generic.edit import CreateView 
from myapp.models import Author 


class AuthorCreate(CreateView) : 
model = Author 
fields = ['name'] 


def form valid(self, form): 
form.instance.created_by = self.request.user 
return super(AuthorCreate, self).form valid(form) 
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注意 ， 这 个 视图 要 使 用 Login_required() 装饰 ， 或 者 在 form_valid() 中 使 用 其 他 方式 处 理 未 授权 的 用 户 。 








C.5.4 Ajax 示例 


下 面 举 个 简单 的 例子 ， 说 明 如 何 实现 既 能 处 理 Ajax 请 求 ， 也 能 处 理 常规 P05T 请 求 的 表单 : 


from django.http import JsonResponse 
from django.views.generic.edit import CreateView 


from myapp.models import Author 


class AjaxableResponseMixin(object): 


def 


def 


form_ invalid(self, form): 
response = super(AjaxableResponseMixin, self).form invalid(form) 
if self.request.is ajax(): 
return JsonResponse(form.errors, status=400) 
else: 
return response 


form valid(self, form): 
# 一 定 要 调用 父 类 的 form_valid() 方法 
# 因为 在 那里 可 能 做 了 些 处 理 
# (对 CreateView 来 说 ， 会 调用 form.save()) 
response = super(AjaxableResponseMixin, self).form valid(form) 
if self.request.is ajax(): 

data = { 

"pk': seLf.object.pk， 

} 

return JsonResponse(data) 
else: 

return response 


class AuthorCreate(AjaxableResponseMixin, CreateView): 
model = Author 
fields = ['name'] 
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附录 D Django 设置 





Django 设置 文件 包含 项 目的 所 有 配置 。 这 篇 附录 说 明 设 置 的 作用 和 可 用 的 设置 。 


D.1 设置 文件 是 什么 ? 














设置 文件 其 实 就 是 一 个 Python 模块 ， 里 面 定义 了 模块 层 变量 。 下 面 是 几 个 设置 示例 : 











ALLOWED_HOSTS = ['www.example.com'] 
DEBUG = False 
DEFAULT_FROM_EMAIL = 'webmaster@Qexample.com' 


如 果 把 DEBUG 设 为 False， 还 要 正确 设置 ALLOWED_HOSTS。 





鉴于 此 ， 设 置 文件 要 遵守 下 述 规则 : 
。 不 能 有 Python 句法 错误 。 
。 可 以 使 用 常规 的 Python 句法 动态 设 定 。 例 如 : MY_SETTING = [str(i) for i in range(30)]。 
。 可 以 从 其 他 设置 文件 中 导入 值 。 

D.1.1 默认 设置 


如 果 某 个 设置 是 不 需要 的 ， 无 需 在 Django 设置 文件 中 设 定 。 每 个 设置 都 有 合理 的 默认 值 。 这 些 默 认 值 在 
django/conf/global_settings.py 模块 中 。 编 译 设置 时 ，Django 采用 下 述 算法 : 


。 从 global_settings.py 中 加 载 设置 。 
。 从 专门 的 设置 文件 中 加 载 设置 ， 必 要 时 覆盖 全 局 设置 。 


注意 ， 设 置 文 件 无 需 导 入 global_settings， 这 样 做 就 画蛇添足 了 。 
D.1.2 查看 改动 的 设置 


查看 与 默认 值 不 同 的 设置 有 简便 的 方法 。python manage.py diffsettings 命令 显示 当前 设置 文件 与 Django 默 
认 设 置 之 间 的 差异 。 详 情 参 见 diffsettings 命令 的 文档 。 





D.2 在 Python 代码 中 使 用 设置 


若 想 在 Django 应 用 中 使 用 设置 ， 导 入 django.conf.settings 对 象 。 例 如 : 


from django.conf import settings 
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if settings.DEBUG: 
# 做 些 事情 

















注意 ，django.conf.settings 不 是 模块 ， 而 是 对 象 。 因 此 无 法 导入 单个 设置 : 








from django.conf.settings import DEBUG # 不 能 这 么 做 

















还 要 注意 ， 不 能 在 代码 中 导入 global_settings 或 设置 文件 。django.conf.settings 对 默认 设置 和 项 目 专用 的 
设置 做 了 抽象 ， 以 便 统 一 接口 。 这 样 做 还 解 耘 了 使 用 设置 的 代码 和 设置 的 位 置 。 























D.3 运行 时 调整 设置 


别 在 运行 时 调整 应 用 程序 的 设置 。 例 如 ， 别 在 视图 中 这 样 做 : 





from django.conf import settings 
settings.DEBUG = True  # 别 这 么 做 | 


只 能 在 设置 文件 中 为 设置 赋值 。 





D.4 安全 性 











设置 文件 中 有 敏感 信息 ， 例 如 数据 库 密码 ， 因 此 要 尽量 限制 访问 。 例 如 ， 可 以 修改 文件 权限 ， 只 让 自己 和 运 
行 Web 服务 器 的 用 户 读 取 。 在 共享 主机 环境 中 尤其 要 注意 。 
























































D.5 自己 定义 设置 


























Django 并 不 禁止 你 为 自己 的 Django 应 用 定义 设置 。 自 己 定义 设置 时 要 遵守 下 述 约定 : 








。 设置 名 称 为 全 大 写 
。 不 要 再 次 使 用 已 存在 的 设置 














值 为 序列 时 ，Django 使 用 元 组 ， 而 不 是 列表 ， 但 这 只 是 一 个 约定 











D.6 DJANGO_SETTINGS_MODULE 


使 用 Django 时 要 告诉 它 你 想 使 用 哪个 设置 文件 。 指 定 的 方法 是 使 用 环境 变量 DJANGO_SETTINGS_MODULE。 这 个 
环境 变量 的 值 应 该 使 用 Python 路 径 句 法 ,例如 mysite.settings。 


























D.6.1 django-admin 实用 命令 


者 每 次 运行 时 传人 设置 模块 。 例 如 (Unix Bash 





响 
[ea 
3 
当 
六 
地 
过 


可 以 使 用 django-admin 命令 一 次 性 设 
shell) : 











export DJANGO_SETTINGS_ MODULE=mysite. settings 
django-admin runserver 


或 (Windows shell) : 


set DJANGO_SETTINGS_ MODULE=mysite.settings 
django-admin runserver 
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手动 指定 设置 模块 使 用 - -settings 命令 行 参数 : 











django-admin runserver --settings=mysite.settings 


D.6.2 在 服务 器 中 (mod_wsgi) 














在 线 上 服务 器 环境 中 要 告诉 WSGI 应 用 程序 使 用 哪个 设置 文件 。 此 时 使 用 os .environ: 














import os 


os.environ['DJANGO_SETTINGS MODULE'] = 'mysite.settings' 


详情 ， 以 及 Django WSGI 应 用 程序 的 其 他 共性 ， 参 见 第 13 章 。 


D. 





7 在 不 设置 DJANGO_SETTINGS_MODULE 的 情况 下 使 用 设置 


有 时 可 能 想 跳 过 DJANG0O_SETTINGS_MODULE 环境 变量 。 例 如 ， 单 独 使 用 模板 系统 时 ， 可 能 不 想 设 置 这 样 一 个 指 
向 设置 模块 的 环境 变量 。 此 时 ， 可 以 手动 配置 Django 的 设置 。 方 法 如 下 : 














django.conf.settings.configure(defauLt_settings ,xxsettings) 


例如 : 


from django.conf import settings 


settings.configure(DEBUG=True, TEMPLATE_DEBUG=True) 

















configure() 接受 任意 多 个 关键 字 参 数 ， 每 个 关键 字 参 数 表 示 一 个 设置 和 它 的 值 。 参 数 名 称 都 应 该 使 用 全 大 写 
字母 ， 而 且 与 真正 的 设置 名 称 一 样 。 如 果 后 面 要 使 用 没 传 给 configure() 的 设置 ，Django 将 使 用 设置 的 默认 
值 。 
















































































在 大 型 应 用 程序 中 使 用 框架 的 部 分 组 件 时 基本 上 必须 这 么 配置 Django， 其 实 ， 也 推荐 这 么 做 。 因 此 ， 通 过 
settings.configure() 配置 时 ，Django 不 会 对 进程 的 环境 变量 做 任何 修改 (原因 参见 TIME_ZONE 的 文档 ) 。 
此 时 ，Django 假定 你 能 完全 掌控 自己 的 环境 。 












































D.7.1 自 定义 默认 设置 

















如 果 想 从 django.conf.global_settings 之 外 的 模块 加 载 默认 值 ， 调 用 configure() 时 可 以 把 default_set- 
tings 参数 (或 第 一 个 位 置 参 数 ) 设 为 提供 默认 值 的 模块 或 类 。 在 下 述 示例 中 ， 默 认 值 来 自 myapp_defaults， 


而 














且 不 管 myapp_defautLts 中 DEBUG 为 何 值 ， 都 把 DEBUG 设 为 True: 


from django.conf import settings 
from myapp import myapp_defaults 


settings.configure(default_settings=myapp_defaults, DEBUG=True) 








下 述 示例 通过 位 置 参数 设 定 myapp_defaults， 与 前 例 等 效 : 




















settings.configure(myapp_defaults, DEBUG=True) 





正常 情况 下 ， 无 需 这 样 覆盖 默认 值 。Django 提供 的 默认 值 足 够 合理 ， 可 以 放心 使 用 。 注 意 ， 如 果 传 人 了 新 的 

















默认 模块 ， 整 个 Django 默认 值 都 将 被 替换 掉 ， 因 此 必须 为 代码 中 可 能 用 到 的 每 个 设置 指定 值 。 完 整 设置 参见 
django.conf.settings.global_settings 模块 。 
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D.7.2 configure() 和 DJANGO_SETTINGS_MODULE 必 选 其 一 


如 果 未 设 定 DJIANG0_SETTINGS_MODULE 环境 变量 ， 在 读 取 设 置 之 前 必须 调用 configure()。 和 否则 ， 首 次 访问 设置 
时 ，Django 将 抛 出 ImportError 异常 。 如 果 设 定 了 DJIANGO_SETTINGS_MODULE， 也 访问 了 设置 ， 而 后 又 调用 
configure()，Django 将 抛 出 RuntimeError 异常 ， 指 明 设 置 已 经 配置 。 为 此 ， 有 个 专门 的 特性 (property) : 























django.conf.settings.configured 
例如 : 


from django.conf import settings 
if not settings.configured: 
settings.configure(myapp_defaults, DEBUG=True) 














此 外 ， 不 能 多 次 调用 configure()， 或 者 访问 设置 之 后 再 次 调用 configure()。 综 上 ，configure() 和 DJAN- 
G0_SETTINGS_MODULE 只 能 二 选 其 一 。 不 能 同时 使 用 ， 也 不 能 都 不 用 。 
































D.8 可 用 设置 
Django 提供 了 大 量 设置 。 为 了 便于 引用 ， 我 把 设置 分 成 了 六 类 ， 一 类 对 应 一 个 表 。 


1， 核 心 设置 〈 表 D-1) 

身份 验证 设置 ( 表 D-2) 

消息 设置 ( 表 D-3) 

会 话 设置 ( 表 D-4) 

Django 网 站 设置 ( 表 D-5) 
态 文件 设置 〈 表 D-6) 


So 


每 个 表 中 都 列 出 了 可 用 的 设置 及 其 默认 值 。 各 个 设置 的 详细 说 明和 用 法 举例 参见 Django 文档 。 


覆盖 设置 时 要 小 心 ， 尤 其 是 覆盖 默认 值 为 非 空 列表 或 字典 的 设置 ， 例 如 MIDDLEWARE_CLASSES 和 
STATICFILES_FINDERS。 别 把 想 使 用 的 Django 功能 对 应 的 组 件 删 掉 了 。 





D.8.1 核心 设置 


表 D-1，Django 核心 设置 























设置 默认 值 
ABSOLUTE_URL_OVERRIDES 全 ( 空 字典 ) 
ADMINS [] ( 空 列表 ) 
ALLOWED_HOSTS [] ( 空 列表 ) 
APPEND_SLASH True 
CACHE_MIDDLEWARE_ALIAS default 
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( 续 ) 











设置 默认 值 
{ 
'default': { 
“BACKEND ' : 
CACHES 
"django.core.cache.backends.Locmem.LocMemCache ' ， 
} 
} 
CACHE_MIDDLEWARE_KEY_PREFIX ''， ( 空 字符 串 ) 
CACHE_MIDDLENARE_SECONDS 600 


CSRF_COOKIE_AGE 
CSRF_COOKIE_DOMAIN 
CSRF_COOKIE_HTTPONLY 
CSRF_COOKIE_NAME 
CSRF_COOKIE_PATH 


CSRF_COOKIE_SECURE 


DATE_INPUT_FORMATS 


DATETIME_FORMAT 


DATETIME_INPUT_FORMATS 


DEBUG 
DEBUG_PROPAGATE_EXCEPTIONS 


DECIMAL_SEPARATOR 


31449600 (1 年 对 应 的 秒 数 ) 


None 


False 


'csrftoken' 


) 


'N j, Y, P' (如 Feb. 4, 2003, 4 p.m.) 


( 


'%Y-%m-%d', 
'%b %d %Y', 
'%d %b %Y', 
'%B %d %Y', 
'%d %B %Y', 


'%Y-%m-%d %H: 
'%Y-%m-%d %H: 
'%Y-%m-%d %H: 


'%Y-%m-%d', 


'%m/%d/%Y %H: 
'%m/%d/%Y %H: 
'%m/%d/%Y %H: 


'%m/%d/%Y' ， 


'%m/%d/%y %H: 
'%m/%d/%y %H: 
'%m/%d/%y %H: 


'%m/%d/%y' ， 


'%m/%d/%Y' , '%m/%d/%y', 


'%b %d, %Y', 
'%d %b, %Y', 
'%B %d, %Y', 
'%d %B, %Y', 


%M:%S ' ， 
%M:%S .%f', 
%M ' ， 


%M:%S ' ， 
%M:%S .%f' ， 
%M ' ， 


%M:%S ' ， 
%M:%S .%f' ， 
%M ' ， 
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( 续 ) 








设置 默认 值 
DEFAULT_CHARSET 'utf-8" 
DEFAULT_CONTENT_TYPE 'text/html' 


DEFAULT_EXCEPTION_REPORTER_FILTER django.views.debug.SafeExceptionReporterFilter 














DEFAULT_FILE_STORAGE django.core.files.storage.FileSystemStorage 
DEFAULT_FROM_EMAIL 'webmaster@localhost'" 
DEFAULT_INDEX_TABLESPACE '' ( 空 字 符 串 ) 

DEFAULT_TABLESPACE '… ( 空 字 符 串 ) 

DISALLOWED_USER_AGENTS [] ( 空 列表 ) 

EMAIL_BACKEND django.core.mail.backends.smtp.EmailBackend 
EMAIL_HOST 'Llocalhost' 

EMAIL_HOST_PASSWORD '' ( 空 字符 串 ) 

EMAIL_HOST_USER '… ( 空 字符 串 ) 

EMAIL_PORT 25 

EMAIL_SUBJECT_PREFIX '[Django] ， 

EMAIL_USE_TLS False 

EMAIL_USE_SSL False 

EMAIL_SSL_CERTFILE None 

EMAIL_SSL_KEYFILE None 

EMAIL_TIMEOUT None 

FILE_CHARSET 'utf-8' 


("django.core.files.uploadhandler .MemoryFileUploadHandler", 
FILE_UPLOAD_HANDLERS 
"django.core.files.uploadhandler.TemporaryFileUploadHandler") 


FILE_UPLOAD MAX_MEMORY_SIZE 2621440 ( 即 2.5 MB) 





FILE_UPLOAD_DIRECTORY_PERMISSIONS None 

















FILE_UPLOAD_PERMISSIONS None 
FILE_UPLOAD_TEMP_DIR None 
FIRST_DAY_OF_WEEK 9 (星期 天 ) 
FIXTURE_DIRS [] ( 空 列表 ) 
FORCE_SCRIPT_NAME None 
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( 续 ) 








设置 默认 值 
FORMAT_MODULE_PATH None 


IGNORABLE_404_URLS 
INSTALLED_APPS 
INTERNAL_IPS 
LANGUAGE_CODE 
LANGUAGE_COOKIE_AGE 
LANGUAGE_COOKIE_DOMAIN 
LANGUAGE_COOKIE_NAME 
LANGUAGES 
LOCALE_PATHS 

LOGGING 
LOGGING_CONFIG 
MANAGERS 

MEDIA_ROOT 


MEDIA_URL 


MIDDLEWARE_CLASSES 


MIGRATION_MODULES 
MONTH_DAY_FORMAT 
NUMBER_GROUPING 

PREPEND_WWW 

ROOT_URLCONF 

SECRET_KEY 
SECURE_BROWSER_XSS_FILTER 
SECURE_CONTENT_TYPE_NOSNIFF 
SECURE_HSTS_INCLUDE_SUBDOMAINS 
SECURE_HSTS_SECONDS 
SECURE_PROXY_SSL_HEADER 
SECURE_REDIRECT_EXEMPT 


SECURE_SSL_HOST 


[] ( 空 列表 ) 
[] ( 空 列表 ) 
[] 〈 空 列表 ) 
er 


None (关闭 浏览 器 后 失效 ) 














None 
'django_Language' 

全 部 可 用 语言 构成 的 列表 
[] 〈 空 列表 ) 


配置 日 志 的 字典 









































'logging.config.dictConfig' 


障 








'”( 空 字符 串 ) 


('django.middleware.common.CommonMiddleware', 
'django.middleware.csrf.CsrfViewMiddleware') 

















{} ( 空 字典 ) 








障 
i 
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( 续 ) 








设置 默认 值 
SECURE_SSL_REDIRECT False 
SERIALIZATION_MODULES 未 定义 
SERVER_EMAIL "rootQLocaLhost' 


SHORT_DATE_FORMAT 
SHORT_DATETIME_FORMAT 
SIGNING_BACKEND 
SILENCED_SYSTEM_CHECKS 
TEMPLATES 
TEMPLATE_DEBUG 


TEST_RUNNER 


TEST_NON_SERIALIZED_APPS 


THOUSAND_SEPARATOR 


TIME_FORMAT 


TIME_INPUT_FORMATS 


TIME_ZONE 

USE_ETAGS 

USE_I18N 

USE_L10N 
USE_THOUSAND_SEPARATOR 
USE_TZ 
USE_X_FORNARDED_HOST 
WSGI_APPLICATION 
YEAR_MONTH_FORMAT 


X_FRAME_OPTIONS 


m/d/Y (如 12/31/2003) 

m/d/Y P (如 12/31/2003 4 p.m. ) 
'django.core. signing.TimestampSigner' 
[] ( 空 列表 ) 

[] ( 空 列表 ) 

False 


'django.test.runner .DiscoverRunner' 


'%H:%M:%S', 
'%H:%M:%S .%f', 
'%H:%M"' ， 

) 


'America/Chicago' 
False 
True 
False 
False 
False 
False 
None 
'F Y， 


"SAMEORIGIN 
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D.8.2 身份 验证 设置 


表 D-2，Django 身份 验证 设置 





设置 


默认 值 





AUTHENTICATION_BACKENDS 
AUTH_USER_MODEL 
LOGIN_REDIRECT_URL 
LOGIN_URL 


LOGOUT_URL 


PASSWORD_RESET_TIMEOUT_DAYS 


PASSWORD_HASHERS 


"django.contrib.auth.backends.ModeLBackend ' 
"auth.User ' 

" /accounts/profiLe/ 

'/accounts/login/' 

'/accounts/logout/' 

3 


('django.contrib.auth.hashers.PBKDF2PasswordHasher ' ， 
"django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher ' ， 
"django.contrib.auth.hashers.BCryptPasswordHasher ' ， 
"django.contrib.auth.hashers.SHA1PasswordHasher ' ， 
"django.contrib.auth.hashers.MD5PasswordHasher ' ， 
"django.contrib.auth.hashers.UnsaLtedMD5PasswordHasher ' ， 
"django.contrib.auth.hashers.CryptPasswordHasher ') 





D.8.3 消息 设置 


表 D-3，Django 消息 设置 





设置 


默认 值 





MESSAGE_LEVEL 


MESSAGE_STORAGE 


MESSAGE_TAGS 


messages.INFO 
'django.contrib.messages.storage.fallback.FallbackStorage' 


{messages.DEBUG: 'debug', 
messages.INFO: 'info', 
messages.SUCCESS: 'success', 
messages .WARNING: 'warning', 
messages.ERROR: 'error'} 





D.8.4 会 话 设置 


表 D-4，Django 会 话 设置 








设置 默认 值 
SESSION_CACHE_ALIAS default 


SESSION_COOKIE_AGE 
SESSION_COOKIE_DOMAIN 
SESSION_COOKIE_HTTPONLY 


SESSION_COOKIE_NAME 


1209600 (2 周 对 应 的 秒 数 ) 
None 
True 


'sessionid' 
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( 续 ) 








设置 默认 值 

SESSION_COOKIE_PATH 2 

SESSION_COOKIE_SECURE False 

SESSION_ENGINE 'django.contrib.sessions.backends.db' 


SESSION_EXPIRE_AT_BROWSER_CLOSE False 





SESSION_FILE_PATH None 
SESSION_SAVE_EVERY_REQUEST False 
SESSION_SERIALIZER 'django.contrib.sessions.serializers.JSONSerializer' 





D.8.5 Django 网 站 设置 


表 D-5，Django 网 站 设置 








设置 默认 值 
SITE_ID 未 定义 





D.8.6 静态 文件 设置 


表 D-6，Django 静态 文件 设置 








设置 默认 值 

STATIC_ROOT None 

STATIC_URL None 

STATICFILES_DIRS [] ( 空 列表 ) 

STATICFILES_STORAGE 'django.contrib.staticfiles.storage.StaticFilesStorage' 


("django.contrib.staticfiles.finders.FileSystemFinder", 


STATICFILES_FINDERS ， 人 a 
"django.contrib.staticfiles.finders.AppDirectoriesFinder") 
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附录 E 内 置 模板 标签 和 过 滤器 








第 3 章 介 绍 了 一 些 最 有 用 的 内 置 模 板 标签 和 过 滤器 。 然 而 ，Django 自 带 的 内 置 标签 和 过 滤器 还 有 很 多 。 这 篇 
附录 概述 Django 中 可 用 的 全 部 模板 标签 和 过 滤器 。 





E.1 内 置 标签 


E.1.1 autoescape 


控制 当前 的 自动 转 义 行为 。 








toescape 标签 结尾 。 


启用 自动 转 义 时 ， 包 含 HTML 的 变量 先 转 义 再 输出 
escape 过 滤器 效果 一 样 

















o 








唯一 的 例外 是 被 生成 变量 的 代码 或 者 通过 safe 或 escape 3 


用 法 举例 : 


{% autoescape on 


{{ body }} 


{% endautoescape 


E.1.2 block 


























%} 


%} 


定义 可 由 子 模板 覆盖 的 块 。 详 情 参 见 3.11 市 。 


E.1.3 comment 


详细 说 明和 使 用 举例 参见 Django 文档 。 











这 个 标签 的 参数 为 on 或 off， 指 明 在 块 中 自动 转 义 是 否 生 效 。 块 以 endau- 














(在 此 之 前 先 应 用 过 滤器 ) 。 这 与 手动 在 各 个 变量 上 应 用 














过 滤器 标记 为 无 需 转 义 的 安全 内 容 。 





忽略 { comment %} 和 {% endcomment %} 之 间 的 全 部 内 容 。 起 始 标签 可 以 添加 可 选 的 注解 ， 例 如 说 明 为 何 要 


注释 掉 代 码 。 








comment 标签 不 能 般 套 。 


E.1.4 csrf_token 


这 个 标签 提供 CSRF 防护 。 关 于 


2 
时 。 


E.1.5 cycle 


每 执行 这 个 标签 一 次 输 
类 推 。 所 有 参数 都 输出 





{% for o in some_ 








跨 站 请 求 伪 造 (Cross Site Request Forgery) 的 详细 信息 参 岂 





出 参数 中 的 一 个 值 。 第 一 次 执行 输出 第 一 





一 裔 之 后 ， 回 到 第 一 个 参数 ， 


list %} 





再 依次 输出 。 


-= 


和 3 章 和 第 19 


攻 











个 参数 ， 第 二 次 执行 输出 第 二 个 参数 ， 以 此 
这 个 标签 在 循环 中 特别 有 用 : 
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<tr class="{% cycle "row1' 'row2' %}"> 


</tr> 
{% endfor %} 














第 一 次 迭代 生成 的 HTML 使 用 rowl 类 ， 第 二 次 迭代 使 用 row2 类 ， 第 三 次 迭代 使 用 rowl 类 ， 以 此 类 推 。 参 
数 的 值 也 可 以 通过 变量 指定 。 假 如 有 两 个 模板 变量 rowvaluel 和 rowvalue2， 可 以 像 这 样 在 二 者 的 值 之 间 切 
换 : 

















{% for o in some_list %} 
<tr class="{% cycle rowvaLue1 rowvaLue2 %}"> 


</tr> 
{% endfor %} 





此 外 ， 也 可 以 混用 变量 和 字符 串 : 





{% for o in some_list %} 
<tr class="{% cycle 'rowl' rowvaLue2 'row3' %}"> 


</tr> 
{% endfor %} 











一 个 cycle 标签 中 可 以 使 用 任意 多 个 值 〈 以 空格 分 开 ) 。 放 在 单 引号 (') 或 双 引 号 (") 中 的 值 视 作 字符 串 
字面 量 ， 没 有 引号 的 视 为 模板 变量 。 











E.1.6 debug 


输出 大 量 调试 信息 ， 包 括 当 前 上 下 文 和 导入 的 模块 。 


E.1.7 extends 











表明 所 在 模板 扩展 某 个 父 模板 。 这 个 标签 有 两 种 用 法 : 

















1. {% extends "base.htmL" %} (有 引号) ， 以 字面 值 "base.html" 为 父 模板 的 名 称 。 

2.{% extends variable %} 以 variable 的 值 为 父 模板 的 名 称 。 如 果 variable 的 求 值 结果 是 一 个 字符 串 ， 
Django 以 那个 字符 串 为 父 模板 的 名 称 ， 如 果 求 值 结果 是 一 个 Tenplate 对 象 ，Django 使 用 那个 对 象 为 
父 模 板 。 

















E.1.8 filter 





使 用 一 个 或 多 个 过 滤器 过 滤 内 容 块 。Django 中 可 用 的 过 滤器 参见 了 .2 市 。 


E.1.9 firstof 


























输出 参数 中 第 一 个 不 为 False 的 变量 值 。 如 果 传 人 的 变量 都 为 False， 不 输出 任何 内 容 。 用 法 示例 : 





{% firstof var1 var2 var3 %} 
等 效 于 : 


{% if var1 %} 
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{{ varl }} 
{% elif var2 %} 

{{ var2 }} 
{% elif var3 %} 

{{ var3 }} 
{% endif %} 


E.1.10 for 





适 代 数组 中 的 各 个 元 素 ， 并 把 当前 迭代 的 元 素 赋值 给 一 个 上 下 文 变量 。 例 如 ， 下 述 代 码 列 出 athlete_list 中 
的 各 位 运动 员 : 


<ul> 

{% for athlete in athlete list %} 
<li>{{ athlete.name }}</li> 

{% endfor %} 

</ul> 





可 以 使 用 {% for obj in list reversed %} 反 向 迭代 列表 。 如 果 需 要 迭代 列表 构成 的 列表 ， 可 以 把 各 个 子 列 
表 拆 包 出 来 ， 赋 予 单独 的 变量 。 访 问 字 典 中 的 元 素 时 也 可 以 这 么 做 。 假 如 上 下 文中 有 个 名 为 data 的 字典 ， 下 
述 代码 显示 它 的 键 和 值 : 






































{% for key, value in data.items %} 


{{ key }}: {{ value }} 
{% endfor %} 


E.1.11 for ... empty 





for 标签 有 个 可 选 的 {% empty %} 子 句 ， 在 指定 的 数组 为 空 或 无 法 找到 时 显示 一 些 文本 。 


<ul> 
{% for athlete in athlete_ list %} 
<li>{{ athlete.name }}</li> 
{% empty %} 
<li>Sorry, no athletes in this list.</li> 
{% endfor %} 
</ul> 


E.1.12 if 











{% if %} 计算 变量 的 值 ， 如 果 为 真 〈 即 存在 、 不 为 空 、 不 是 假 值 ) ， 输 出 块 中 的 内 容 : 














{% if athLete_List %} 

Number of athLetes: {{ athlete_ list|length }} 
{% elif athlete_ in locker_room list %} 

Athletes should be out of the locker room soon! 
{% else %} 

No athletes. 
{% endif %} 




















在 上 述 代 码 中 ， 如 果 athlete_list 不 为 空 ，{{ athlete_list|length }} 将 显示 运动 员 的 数量 。 可 以 看 出 ，if 
标签 可 以 有 一 个 或 多 个 {% elif 时 子 句 ， 以 及 一 个 {% else 时 子 句 ， 在 前 述 条 件 判断 都 失败 时 显示 。 这 些 子 
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句 都 是 可 选 的 。 


布尔 运算 符 





if 标签 可 以 使 


{% 


{% 


{% 


{% 


{% 


{% 


同一 个 标签 中 可 以 同时 使 




















| and、or 或 not 测试 多 个 变量 或 取 反 指定 的 变量 : 





Both athletes and coaches are available. 


There are some athletes or some coaches. 


if athlete_list and coach_list %} 
endif %} 

if not athlete_list %} 

There are no athletes. 

endif %} 

if athlete_list or coach_ list %} 
endif %} 




















] and 和 or ， 前 者 的 优先 级 较 高 。 例 如 : 


{% if athlete_list and coach_list or cheerleader_list %} 


是 这 样 解释 的 : 





if (athlete_list and coach_List) or cheerleader_list 











但 是 ， 





if 标签 














在 证 标签 中 使 用 括号 是 无 效 的 句法 。 如 果 想 指明 优先 级 ， 应 该 使 用 谨 套 的 if 标签 。 
还 可 以 使 用 ==、!= 


~ 、\ 











>、<=、>= 和 in 等 运算 符 ， 各 自 的 作用 参见 表 E-1。 














表 E-1， 模 板 标签 中 的 布尔 运算 符 











运算 符 示例 

三 三 {% if somevar == x %} ... 

!= {% if somevar != x %} . 

< {% if somevar < 100 %} .… 

> {% if somevar > 10 %} .… 

<= {% if somevar <= 100 %} ... 

>= {% if somevar >= 10 %} ... 

in {% if bc in abcdef %} 
复杂 的 表达 式 








上 述 运 算 符 可 以 结合 起 来 构成 复杂 的 表达 式 。 此 时 ， 要 知道 表达 式 是 如 何 计算 的 ， 即 优先 级 规则 。 这 些 运算 
符 的 优先 级 从 低 到 高 如 下 所 示 : 
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。 not 
。 in 


e ==， !=， < 


这 与 Python 中 的 优先 级 完全 一 样 。 











在 话 表 达 式 中 还 可 以 使 用 过 滤器 。 例 如 : 


{% if messages|Length >= 100 %} 
You have Lots of messages today! 
{% endif %} 


E.1.13 ifchanged 





检查 前 一 次 磷 代 之 后 值 是 否 变 了 。{% ifchanged %] 块 标签 在 循环 中 使 用 。 有 两 种 














1. 检查 演 染 得 到 的 内 容 ， 与 之 前 的 状态 比较 ， 只 在 有 变化 时 显示 内 容 。 
2. 检查 指定 的 一 个 或 多 个 变量 的 值 是 否 有 变化 。 


























E.1.14 ifequal 





两 个 参数 相等 时 输出 块 中 的 内 容 。 例 如 : 
{% ifequal user.pk comment.user_id %} 
{% endifequal %} 


可 用 if 标签 和 == 运算 符 代替 ifequal 标签 。 





E.1.15 ifnotequal 


与 ifequal 类 似 ， 不 过 测试 的 是 两 个 参数 是 否 不 等 。 可 用 if 和 != 运算 符 代替 。 





E.1.16 incLude 





加 载 一 个 模板 ， 在 当前 上 下 文中 泻 染 。 这 是 在 模板 中 引入 其 他 模板 的 方式 。 模 板 的 名 称 可 以 是 一 个 变量 : 


{% include template name %} 
或 者 硬 编码 的 字符 串 (有 引号 ) : 


{% include "foo/bar.html" %} 


E.1.17 Load 

















法 : 


史 





加 载 自 定义 的 模板 标签 。 例 如 ， 下 述 模板 代码 加 载 somelibrary 和 package 包 中 otherlibrary 注册 的 全 部 标 





答 和 过 滤器 ; 


{% Load somelibrary package.otherlibrary %} 
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此 外 ， 还 可 以 使 用 fron 参数 有 选择 地 从 库 中 加 载 具体 的 过 滤器 和 标签 。 
下 述 示例 从 somelibrary 中 加 载 名 为 foo 和 bar 的 标签 或 过 滤器 : 





{% Load foo bar from somelibrary %} 


详情 参见 8.7 节 。 


E.1.18 Lorem 














显示 随机 的 占 位 拉丁 文本 。 可 用 于 为 模板 提供 示例 数据 。 用 法 : 


{% Lorem [count] [method] [random] %} 





{% lorem %} 标签 可 接受 零 个 、 一 个 、 两 个 或 三 个 参数 。 这 些 参数 分 别 是 : 























1. count: 一 个 数字 (或 变量 ) ， 指 定 生成 的 段落 或 单词 数量 (默认 为 1) 。 
2. method: 为 表示 单词 的 w、 表 示 HTML 段落 的 p 或 表示 纯 文 本 段落 的 b (默认 为 b) 。 
3. random: 生成 文本 时 随机 输出 (指定 时 ) ， 不 使 用 常见 的 段落 (Lorem ipsum dolor sit amet...) 。 






































例如 ，{% Lorem 2 w random %} 随机 输出 两 个 拉丁 单词 。 





Co 


E.1.19 now 











以 参数 指定 的 格式 显示 当前 日 期 和 (或) 时 间 。 参 数 中 可 用 的 格式 说 明 符 参 见 date 过 滤器 。 例 如 ， 
It is {% now "jS F Y H:i" %} 


传人 的 格式 也 可 以 是 某 个 预定 义 的 值 ， 如 DATE_FORMAT、DATETIME_FORMAT、 SHORT_DATE_FORMAT 或 SHORT_DATE- 
TIME_FORMAT。 预 定义 格式 的 输出 内 容 根据 当前 本 地 化 设置 和 是 否 启用 本 地 化 格式 而 有 所 不 同 。 例 如 : 


It is {% now "SHORT_DATETIME_FORMAT" %} 


E.1.20 regroup 





按 共 有 属性 重新 分 组 一 组 相似 的 对 象 。 
{% regroup %} 生成 分 组 对 象 构成 的 列表 。 每 个 分 组 对 象 有 两 个 属性 : 






































。 grouper: 分 组 的 依据 (如 字符 串 "India" 或 "Japan") 
。 list: 分 组 中 的 元 素 列表 (如 国家 为 "India" 的 城市 列表 ) 























注意 ，{% regroup 各 不 排序 输入 1 
任何 有 效 的 模板 查找 对 象 都 是 有 效 的 分 组 属性 ， 包 括 方法 、 属 性 、 字 — 典 的 键 和 列表 的 元 素 。 























E.1.21 spaceless 








删除 HTML 标签 之 间 的 空白 ， 包 括 制 表 符 和 换行 符 。 用 法 示例 : 











{% spaceless %} 


<p> 
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<a href="foo/">Foo</a> 
< /ps> 
{% endspaceless %} 
这 个 示例 返回 的 HTML 如 下 : 


<p><a href="foo/">Foo</a></p> 


E.1.22 templatetag 











输出 构成 模板 标签 句法 的 字符 。 模 板 系 统 自身 无 法 转 义 ， 因 此 若 想 显示 构成 模板 标签 的 字符 ， 必 须 使 用 {% 
templatetag %} 标签 。 参 数 指 明 输 出 模板 标签 的 哪 一 部 分 : 





。 openblock 输出 你 


。 closeblock 输出 纷 





。 openvariable 输出 {{ 
。 closevariable 输出 }} 


。 openbrace 输出 { 


。 closebrace 输出 } 





。 opencomment 输出 人 # 





。 closecomment 输出 #} 
用 法 示例 : 

{% templatetag openblock %} url 'entry_list' {% templatetag closeblock %} 
E.1.23 url 


返回 指定 视图 函数 和 可 选 参 数 对 应 的 绝对 路 径 (不 带 域 名 的 URL) 。 路 径 中 的 特殊 字符 会 使 用 iri_to_uri() 
编码 。 使 用 这 种 方式 输出 链接 符合 DRY 原则 ， 因 为 无 需 在 模板 中 硬 编 码 URL。 






































{% url 'some-url-name' v1 v2 %} 


第 一 个 参数 是 视图 函数 的 路 径 ， 格 式 为 package.package.module.function， 可 以 是 放 在 引号 里 的 字面 量 ,， 也 
可 以 是 上 下 文 变量 。 余 下 的 参数 是 可 选 的 ， 以 空格 分 开 ， 用 于 指定 URL 中 的 参数 。 





E.1.24 verbatim 














不 让 模板 引 警 泻 染 块 中 的 内 容 。JavaScript 模板 层 经 常 使 用 这 个 标签 防止 与 Django 的 句法 冲突 。 














E.1.25 widthratio 
































插入 条 形 图 等 图 像 时 用 于 计算 上 至 某 个 值 的 长 宽 比 ， 然 后 把 这 一 比例 规整 。 例 如 : 





<img src="bar.png" alt="Bar" height="10" width="{% widthratio this_value max_value max_width 


%}" /> 
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E.1.26 with 


把 复杂 的 变量 缓存 到 一 个 简单 的 名 称 下 。 多 次 访问 耗资 源 的 【如 访问 数据 库 ) 方法 时 可 以 这 么 做 。 例 如 : 


{% with total=business.employees.count %} 
{{ total }} employee{{ totaL|pLuraLize }} 
{% endwith %} 


E.2 内 置 过 滤器 


E.2.1 add 
把 参数 加 到 值 上 。 例 如 : 
{{ valueladd:"2" }} 
如 果 value 为 4， 输 出 6。 
E.2.2 addslashes 
在 引号 前 加 上 和 斜 线 。 可 用 于 转 义 CSV 中 的 字符 串 。 例 如 : 
{{ value|laddslashes }} 
如 果 value 为 "I'm using Django"， 输 出 "I\'m using Django"。 
E.2.3 capfiirst 
把 值 的 首 字 母 变 成 大 写 。 如 果 第 一 个 字符 不 是 字母 ， 这 个 过 滤器 没有 效果 。 
E.2.4 center 
在 指定 宽度 中 居中 显示 值 。 例 如 
"{{ value|center:"14" }}" 
如 果 value 为 "Django" ， 输 出 "Django ”(.- 表示 一 个 空格 ) 。 
E.2.5 cut 


从 字符 串 中 删除 参数 指定 的 值 。 


E.2.6 date 


使 用 指定 的 格式 格式 化 日 期 。 格 式 与 PHP 的 date() 函数 类 似 ， 不 过 有 些 区 别 。 


这 些 格式 字符 只 能 在 Django 的 模板 中 使 用 ， 设 计时 考虑 到 便于 设计 师 迁 移 ， 因 此 与 PHP 采用 
的 格式 兼容 。 完 整 的 格式 字符 串 参 见 Django 文档 。 
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例如 : 


{{ valueldate:"DdMY" }} 











如 果 value 是 一 个 datetime 对 象 (例如 datetime.datetime.now() 的 结果 ) ， 输 出 的 字符 串 类 似 于 "Fri 01 
Jul 2016"。 也 可 以 传人 预定 义 的 格式 DATE_FORMAT、DATETIME_FORMAT、 SHORT_DATE_FORMAT 或 SHORT_DATE- 





TIME_FORMAT， 以 及 使 用 日 期 格式 说 明 符 自 定义 的 格式 。 














E.2.7 default 





如 果 value 是 假 值 ， 使 用 指定 的 默认 值 ， 否 则 ， 使 用 value 的 值 。 例 如 : 





{{ valueldefault:"nothing"” }} 


E.2.8 default_if_none 











当 且 仅 当 vatlue 为 None 时 使 用 指定 的 默认 值 ， 否 则 使 用 vatue 的 值 。 














E.2.9 dictsort 























按 参 数 指定 的 键 排序 字典 构成 的 列表 ， 返 回 排序 后 的 列表 。 例 如 : 











{{ valueldictsort:"name" }} 


E.2.10 dictsortreversed 

















按 参 数 指定 的 键 排序 字典 构成 的 列表 ， 返 回 反 向 排序 后 的 列表 。 




















E.2.11 divisibleby 





如 果 值 能 被 参数 整除 ， 返 回 True。 例 如 : 


{{ valueldivisibleby:"3" }} 





如 果 value 为 21， 返 回 True。 


E.2.12 escape 














转 义 字符 串 中 的 HIML。 具 体 而 言 ， 是 做 下 述 蔡 换 : 











。 < 转换 成 &Lt; 

。 > 转换 成 &gt; 

。， ( 单 引 号 ) 转换 成 &#39; 
。“" ( 双 引 号 ) 转换 成 &quot; 
。 & 转换 成 &amp; 








沽 荔 
。 FF 








字符 囊 时 才 做 转 义 ， 因 此 在 一 串 过 滤器 中 escape 放 在 什么 位 置 没 关系 ， 它 始终 作为 最 后 一 个 过 滤器 应 
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E.2.13 escapejs 


转 义 JavaScript 字符 串 中 的 字符 。 这 个 过 滤器 得 到 的 结果 不 能 在 HTML 中 安全 使 用 ,但 是 使 用 模板 生成 
JavaScript/JSON 时 能 防止 句法 出 错 。 








E.2.14 filesizeformat 


把 值 格式 化 为 人 类 可 读 的 文件 大 小 (如 '13 KB'、'4.1 MB'、'102 bytes'， 等 等 ) 。 例如: 





{{ valuelfilesizeformat }} 





如 果 value 为 123456789， 输 出 117.7 MB。 


E.2.15 first 


回 列表 中 的 第 一 个 元 素 。 











可 


E.2.16 floatformat 








不 指定 参数 时 ， 近 似 浮 点 数 ， 只 保留 一 位 小 数 (前提 是 有 小 数 ) 。 如 果 指 定 了 整数 参数 ，floatformat 近似 时 
保留 相应 位 数 的 小 数 。 




















如 果 value 为 34.23234，{{ value|floatformat:3 }} 输出 34.232。 


E.2.17 get_digit 











从 一 个 数字 中 取 回 指定 的 那 一 位 ，1 表示 最 低位 。 


E.2.18 iriencode 


把 IRI (Internationalized Resource Identifier， 国 际 化 资源 标识 符 ) 转换 成 适合 在 URL 中 使 用 的 字符 串 。 





E.2.19 join 





使 用 字符 串 连 接 列 表 ， 类 似 于 Python 的 str.join(list)。 





E.2.20 last 


回 列表 中 的 最 后 一 个 元 素 。 








沿 


E.2.21 Length 





回 值 的 长 度 。 字 符 串 和 列表 都 适用 。 





沿 


E.2.22 length is 





如 果 值 的 长 度 与 参数 相等 ， 返 回 True， 和 否则 返回 False。 例 如 : 





{{ valuellength is:"4"” }} 
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E.2.23 linebreaks 





把 纯 文 本 中 的 换行 蔡 换 成 适当 的 HTML 标签 。 一 个 换行 符 蔡 换 成 一 个 HTML <br /> 标签， 换行 之 后 还 有 新 
行 则 替换 成 段落 结束 标签 (</p>) 。 








E.2.24 linebreaksbr 


把 纯 文 本 中 的 所 有 换行 都 替换 成 HIML <br /> 标签 。 

















E.2.25 linenumbers 
显示 带 有 行 号 的 文本 。 


E.2.26 ljust 





在 指定 宽度 中 左 对 齐 值 。 例 如 : 


{{ value|lljust:"10" }} 








如 果 value 为 "Django"， 和 输出 "Django____"” (表示 一 个 空格 ) 。 


E.2.27 Lower 
把 字符 串 转换 成 全 小 写 形式 。 
E.2.28 make_list 


把 值 转换 成 列表 。 值 为 字符 串 时 ， 返 回 各 字母 构成 的 列表 。 值 为 整数 时 ， 先 把 参数 转换 成 Unicode 字符 串 ， 
然后 再 创建 列表 。 


E.2.29 phone2numeric 


把 电话 号 码 〈 可 能 包含 字母 ) 转换 成 等 效 的 数值 。 输 入 无 需 是 有 效 的 电话 号 码 ， 任 何 字符 串 都 能 转换 。 例 
如 : 





{{ value|lphone2numeric }} 








如 果 value 为 800-COLLECT， 输 出 800-2655328。 


E.2.30 pluralize 
值 不 为 1 时 返回 复数 后 级 。 默 认 后 级 为 "s"。 
单词 复数 变形 较为 复杂 时 ， 可 以 指定 单数 和 复数 后 级 ， 以 逗号 分 开 。 例 如 : 





























You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}. 


E.2.31 pprint 


对 pprint.pprint() 的 包装 ， 用 于 调试 。 
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E.2.32 random 





回 指定 列表 中 的 一 个 随机 元 素 。 





启 


E.2.33 rjust 


在 指定 宽度 中 右 对 齐 值 。 例 如 : 














{{ value|lrjust:"10" }} 








如 果 value 为 "Django"， 输 出 "____Django” (表示 一 个 空格 ) 。 


E.2.34 safe 














标记 字符 串 在 输出 之 前 无 需 进 一 步 转 义 HTML。 关 闭 自动 转 义 时 这 个 过 滤器 没有 


洗 
谋 

















E.2.35 safeseq 











把 safe 过 滤器 应 用 到 序列 中 的 各 个 元 素 上 。 可 以 与 其 他 作用 于 序列 的 过 滤器 合用 (如 join) 。 例 如 : 

















{{ some_list|safeseq|join:", " }} 


此 时 不 能 直接 使 用 safe 过 滤器， 因为 它 先 把 变量 转换 成 字符 串 ， 而 不 是 处 理 序列 中 的 单个 元 素 。 








E.2.36 slice 


XX\ 


返回 列表 的 切片 。 句 法 与 Python 的 列表 切片 一 样 。 








E.2.37 slugify 





转换 成 ASCII。 把 空格 转换 成 连 字符 。 把 字母 、 数字、 下 划 线 和 连 字符 之 外 的 字符 删除 。 转 换 成 小 写 。 去 掉 
首尾 的 空白 。 











E.2.38 stringformat 



































根据 参数 指定 的 格式 说 明 符 格式 化 变量 。 说 明 符 使 用 Python 字符 串 格 式 化 句法 ， 但 是 不 用 前 导 %。 








[ 


E.2.39 striptags 


尽 全 力 去 除 COHTML 标签 。 例 如 : 





{{ value|striptags }} 


E.2.40 time 


使 用 指定 格式 格式 化 时 间 。 与 date 过 滤器 一 样 ， 可 以 是 预定 义 的 TIME_FORMAT， 也 可 以 是 自 定义 的 格式 。 

















E.2.41 timesince 
































把 日 期 格式 化 为 距 某 一 刻 的 时 间 (如 “4 days,6 hours”") 。 有 个 可 选 的 参数 ， 指 定 比 较 的 日 期 基点 (如 不 指 
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定 ， 与 now 比较 ) 。 


E.2.42 timeuntil 














距 指 定 日 期 或 日 期 时 间 的 跨度 。 








E.2.43 title 


























把 字符 串 转 换 成 标题 格式 ， 即 单词 首 字母 大 写 ， 其 余 字 母 小 写 。 


E.2.44 truncatechars 


字符 串 的 字符 串 超 过 指定 长 度 时 截断 。 截 断后 的 字符 串 以 可 翻译 的 省 略 号 (…) 结尾 。 例 如 : 




















{{ value|truncatechars:9 }} 


E.2.45 truncatechars_htmL 


与 truncatechars 类 似 ， 不 过 知道 如 何 截 断 HTML 标签 。 


E.2.46 truncatewords 

















在 指定 的 单词 个 数 后 截断 字符 串 。 








E.2.47 truncatewords_html 


与 truncatewords 类 似 ， 不 过 知道 如 何 截 断 HTML 标签 。 


E.2.48 unordered list 








递归 遍历 敬 套 的 列表 ， 返 回 一 个 HTML 无 序列 表 (不 含 起 始 和 结束 标签 ) 。 





E.2.49 upper 
把 字符 串 转换 成 全 大 写字 母 形式 。 
E.2.50 urlencode 


转 义 ， 以 便 在 URL 中 使 用 。 








E.2.51 urlize 


把 文本 中 的 URL 和 电子 邮件 地 址 转换 成 可 点 击 的 链接 。 支 持 以 http://、https:// 或 www. 开头 的 URL。 


E.2.52 urlizetrunc 














与 urlize 一 样 ， 把 URL 和 电子 邮件 地 址 转换 成 可 点 击 的 链接 ， 但 是 在 指定 的 字符 长 度 处 截断 URL。 例 如 : 
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{{ value|lurlizetrunc:15 }} 





如 果 value 为 "Check out www.djangoproject.com"， 输 出 "Check out <a href="http://www.djangopro- 
ject.com"” reL="nofoLLow">www.djangopr..</a>"。 与 urlize 一 样 ， 这 个 过 滤器 只 应 该 应 用 于 纯 文 本 。 





E.2.53 wordcount 
返回 字数 。 

E.2.54 wordwrap 
在 指定 的 长 度 处 换行 。 


E.2.55 yesno 





把 True、False 和 None (可 选 ) 映射 到 字符 串 “yes”、“no”“maybe" 上 ， 或 者 是 通过 参数 传人 的 列表 上 (以 
逗号 分 隔 ) ， 根 据 真 假 值 情 况 ， 返 回 相 应 的 字符 串 。 例 如 : 























{{ value|lyesno:"yeah,no,maybe" }} 


E.3 国际 化 标签 和 过 滤器 














Django 提供 了 能 在 模板 中 控制 国际 化 行为 的 标签 和 过 滤器 。 使 用 这 些 标签 和 过 滤器 可 以 细致 控制 翻译 、 格 式 
化 和 时 区 转换 。 

















E.3.1 ii8n 





























这 个 库 用 于 指定 模板 中 可 翻译 的 文本 。 若 想 使 用 这 个 库 ， 把 USE_I18N 设 为 True， 然 后 使 用 {% load ii8n %} 
加 载 。 


E.3.2 L10n 

















这 个 库 用 于 本 地 化 模板 中 的 文本 。 为 此 ， 只 需 使 用 {% Load 1L16n %} 加 载 这 个 库 ， 不 过 通常 都 会 把 USE_L16N 
设 为 True， 因 此 本 地 化 默认 已 启用 。 




















E.3.3 tz 

















这 个 库 的 作用 是 在 模板 中 控制 时 区 转换 。 与 L116n 类 似 ， 只 需 使 用 {% load tz 好 加 载 这 个 库 ， 不 过 通常 都 会 
把 USE_Tz 设 为 True， 因 此 默认 就 会 转换 成 当地 时 间 。 参 见 文 档 。 




















E.4 其 他 标签 和 过 滤器 库 


E.4.1 static 

















为 了 链接 保存 在 STATIC_RO0OT 中 的 静态 文件 ，Django 提供 了 static 模板 标签 。 不 管用 不 用 RequestContext， 
都 可 以 使 用 这 个 标签 。 























{% Load static %} 
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<img src="{% static "images/hi.jpg" %}" alt="Hi!" /> 


此 外 ， 还 可 以 使 用 上 下 文 变量 。 假 如 向 模板 传人 了 user_stylesheet 变量 : 





{% Load static %} 
<link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen" /> 


如 果 只 想 获取 静态 文件 的 URL， 而 不 显示 ， 可 以 使 用 稍微 不 同 的 调用 方式 : 


{% Load static %} 
{% static "images/hi.jpg" as myphoto %} 
<img src="{{ myphoto }}"></img> 





staticfiles 应 用 也 提供 了 static 标签 ， 它 使 用 staticfiles 的 STATICFILES_STORAGE 设置 构建 指定 路 径 的 
URL (而 不 是 仅仅 把 STATIC_URL 设置 和 指定 路 径 传 给 urLLib.parse.urLjoin()) 。 如 果 使 用 云 服 务 伺 服 静 态 
文件 ， 要 使 用 这 个 标签 。 例 如 : 








{% load static from staticfiles %} 
<img src="{% static "images/hi.jpg" %}" alt="Hi!" /> 


E.4.2 get_ static prefix 

















多 数 情况 下 ， 应 该 使 用 Django 自 带 的 static 标签 ， 如 果 想 更 好 地 控制 在 何 处 以 及 如 何 插入 STATIC_URL， 可 
以 使 用 get_static_prefix 标签 。 

















{% load static %} 
<img src="{% get_static prefix %}images/hi.jpg" alt="Hi!" /> 


如 果 需 要 多 次 使 用 这 个 值 ， 可 以 像 下 面 这 样 编写 代码 ， 避 免 额 外 消耗 : 


{% Load static %} 
{% get_ static prefix as STATIC_PREFIX %} 


<img src="{{ STATIC_PREFIX }}images/hi.jpg" alt="Hi!" /> 
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" alt="Hello!" /> 


E.4.3 get_ media prefix 


与 get_static_prefix 类 似 ，get_media_prefix 获取 媒体 文件 前 级 MEDIA_URL。 例如: 


<script type="text/javascript" charset="utf-8"> 
var media path = '{% get media prefix %}'; 
</SCeripts 





I 





此 外 ，Django 还 提供 了 其 他 模板 标签 库 ， 若 想 使 用 ， 要 在 INSTALLED_APPS 设置 中 列 出 ， 然 后 在 模板 中 使 用 


{% load %} 标签 加 载 。 
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附录 F 请 求 和 响应 对 和 象 





Django 使 用 请 求 和 响应 对 象 在 系统 中 传递 状态 。 














请 求 一 个 页 面 时 ，Django 创建 一 个 HttpRequest 对 象 ， 附 带 请 求 的 元 数据 。 然 后 Django 加 载 适 当 的 视图 ， 把 
HttpRequest 对 象 作 为 第 一 个 参数 传 给 视图 函数 。 视 图 则 返回 一 个 HttpResponse 对 象 。 

















本 篇 附录 说 明 HttpRequest 和 HttpResponse 对 象 的 API。 二 者 在 django.http 模块 中 定义 。 
F.1 HttpRequest 对 象 


F.1.1 属性 








如 未 说 明 ， 应 该 把 属性 视 为 只 读 的 。session 是 个 例外 。 


HttpRequest .scheme 











一 个 字符 串 ， 表 示 请 求 模式 (通常 是 http 或 https) 。 


HttpRequest.body 





HTTP 请 求 的 原始 主体 ， 类 型 为 字 节 字符 串 。 原 始 主体 可 用 于 处 理 HTML 之 外 的 格式 ， 如 图 像 、XML 载荷 
等 。 常 规 的 表单 数据 使 用 HttpRequest .POST 处理。 















































还 可 以 使 用 类 似 文件 的 接口 读 取 HttpRequest。 人 参见 HttpRequest .read()。 








HttpRequest.path 





太 舍 器 


一 个 字符 串 ， 表 示 所 请 求 页 面 的 完整 路 径 (不 含 域名 ) 。 

















例如 : /music/bands/the_beatles/。 


HttpRequest.path_info 














在 某 些 Web 服务 器 配置 下 ，URL 中 主机 名 后 面 的 部 分 分 成 脚本 前 级 和 路 径 信息 。 不 管 使 用 哪个 Web 服务 
髓 ，path_info 属性 的 值 始终 是 路 径 信 息 部 分 。 在 代码 中 用 path_info 代替 path 便于 在 测试 和 线 上 服务 器 之 
间 切 换 。 






























































例如 ， 如 果 把 应 用 程序 的 wsGIScriptAlias 设 为 /minfo， 那 么 path 的 是 可 能 是 /minfo/music/bands/the_bea- 
tles/， 而 path_info 的 值 则 是 /music/bands/the_beatles/。 








HttpRequest .method 








一 个 字符 串 ， 表 示 发 起 请 求 所 用 的 HTTP 方法 。 值 始终 为 大 写 形式 。 例 如 : 


if request.method == 'GET': 
do_something() 
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elif request.method == 'POST': 
do_something_else() 


HttpRequest.encoding 

















一 个 字符 串 ， 表 示 用 于 解码 表单 数据 的 编码 (或 者 为 None， 表 示 使 用 DEFAULT_CHARSET 设置 ) 。 访 问 表单 数 
据 时 可 以 重 设 这 个 属性 的 值 。 这 样 ， 后 续 对 属性 的 访问 (例如 读 取 GET 或 PoST 数据 ) 都 使 用 新 设 的 encoding 
值 。 如 果 知 道 表单 数据 的 编码 与 DEFAULT_CHARSET 不 同 ， 可 以 这 么 做 。 













































































HttpRequest .GET 














一 个 类 似 字 典 的 对 象 ， 包 含 所 有 HTTP GET 参数 。 人 参见 F.2 市 。 





HttpRequest.POST 











一 个 类 似 字典 的 对 象 ， 包 含 所 有 HTTP POST 参数 (前 提 是 请 求 中 有 表单 数据 ) 。 参 见 F.2 市 。 


如 果 想 访问 请 求 中 的 原始 数据 或 非 表 单数 据 ， 通 过 HttpRequest.body 属性 访问 。 
























































POST 请 求 可 以 发 送 空 的 PO0ST 字典 。 例 如 ， 通 过 HTTP P0ST 方法 请 求 表单 ， 但 是 不 包含 任何 表单 数据 。 因 此 
不 能 使 用 if request.P0ST 检测 是 不 是 PoST 方法 ; 正确 的 做 法 是 使 用 if request.method == 'P0ST' (参见 前 
文 ) 。 


注意 ，PoST 字典 中 没有 文件 上 传 信息 。 参 见 FILES。 









































HttpRequest. COOKIES 























个 标准 的 Python 字典 ， 包 含 所 有 cookie。 键 和 值 都 是 字符 串 。 

















HttpRequest.FILES 








一 个 类 似 字 典 的 对 象 ， 包 含 所 有 的 上 传 文件 。FILES 中 的 各 个 键 是 <input type="file" name="" /> 标签 nane 
属性 的 值 ， 值 则 是 UploadedFile 对 象 。 





























注意 ， 只 有 请 求 方法 为 PoST， 而 且 <form> 标签 设 定 了 enctype="multipart/form-data" 属性 ，FILES 中 才 有 数 
据 。 和 否则 ，FILES 是 个 空 的 类 似 字 典 的 对 象 。 














HttpRequest .META 





Sn 
人 


一 个 标准 的 Python 字典 ， 包 含 所 有 可 用 的 HITP 首部 。 具 体 有 哪些 首部 ， 取 决 于 客户 端 和 服务 器 ， 下 夯 
个 例子 : 


所 





























。 CONTENT_LENGTH: 请 求 主体 (字符 串 形式 ) 的 长 度 。 
。 CONTENT_TYPE: 请 求 主体 的 MIME 类 型 。 


。 HTTP_ACCEPT_ENCODING: 可 接受 的 啊 应 编码 。 











。 HTTP_ACCEPT_LANGUAGE: 可 接受 的 啊 应 语言 。 
。 HTTP_HOST: 客户 端 发 送 的 HITP Host 首部 。 
。 HTTP_REFERER: 前 一 个 页 面 (如 果 有 ) 。 

。 HTTP_USER_AGENT: 客户 端的 用 户 代理 字符 号 
。 QUERY_STRING: 查询 字符 串 ， 作 为 一 个 整体 (未 经 解析 ) 。 

















Ud 
o 
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。 REMOTE_ADDR: 客户 端的 卫 地 址 。 

。 REMOTE_HOST: 客户 端的 主机 名 。 

。 REMOTE_USER: 通过 Web 服务 器 验证 身份 的 用 户 (如 果 有 ) 。 
。 REQUEST_METHOD : 一 个 字符 串 ， 如 "GET" 或 "POST"。 

。 SERVER_NAME: 服务 器 的 主机 名 。 

。 SERVER_PORT: 服务 器 的 端口 《字符 串 ) 。 








除了 CONTENT_LENGTH 和 CONTENT_TYPE 之 外 ， 请 求 的 HTTP 首部 转换 成 META 键 的 方式 是 ， 把 所 有 字母 变 成 大 
写 ， 连 字符 替换 成 下 划 线 ， 然 后 加 上 HTTP_ 前缀。 因此 ，X-Bender 首部 在 META 属性 中 的 键 是 HTTP_X_BEN- 
DER 。 

















HttpRequest .User 





一 个 AUTH_USER_MODEL 类 型 的 对 象 ， 表 示 当 前 登录 的 用 户 。 如 果 未 登录 ，user 是 django.contrib.auth.mod- 
eLs.AnonymousUser 的 实例 。 可 以 使 用 is_authenticated() 区 分 二 者 ， 例 如 : 


if request.user.is_authenticated(): 
# 针对 已 登录 用 户 
else: 


# 针对 匿名 用 户 


只 有 激活 了 AuthenticationMiddleware 才 有 user 属性 。 


HttpRequest.session 























一 个 类 似 字典 的 对 象 ， 可 读 可 写 ， 表 示 当 前 会 话 。 只 有 启用 了 会 话 功能 才 有 这 个 属性 。 








HttpRequest.urlconf 








不 是 Django 自己 定义 的 ， 但 是 如 果 其 他 代码 (如 自 定 义 的 中 间 件 类 ) 设 定 了 就 可 读 取 。 有 这 个 属性 时 ， 用 作 
当前 请 求 的 根 URL 配置 ， 把 ROOT_URLCONF 设置 覆 善 掉 。 

















HttpRequest.resolver_match 





一 个 ResolverMatch 实例 ， 表 示人 解析 出 来 的 URL。 只 有 人 解析 了 URL 才 会 设 定 这 个 属性 ， 因 此 只 在 视图 中 可 
用 ， 而 不 能 在 中 间 件 方法 中 使 用 ， 因 为 中 间 件 方法 在 解析 URL 之 前 执行 (例如 process_request， 此 时 可 以 
使 用 process_view 代替 ) 。 


























F.1.2 方法 


HttpRequest.get_host() 














返回 通过 HTTP_X_FORNARDED_HOST (如 果 启 用 了 USE_Xx_FORWARDED_HOST) 和 HTTP_HOST 首部 中 的 信息 (以 此 顺 
序 ) 确定 的 源 主机 。 如 果 据 此 得 不 到 值 ， 这 个 方法 按照 PEP 3333 所 述 的 方式 ， 把 SERVER_NAME 和 SERV- 
ER_PORT 连接 在 一 起 。 






































例如 : 127.0.0.1:8000。 


a 
迁 筷 
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如 果 主 机 在 多 个 代理 后 面 ，get_host() 方法 无 法 返回 值 。 一 种 解决 方法 是 使 用 中 间 件 重 写 代理 首部 ， 如 下 述 
示例 所 示 : 











Tt 














class MultiplePproxyMiddleware(object): 
FORWARDED_FOR_FIELDS = [ 
'HTTP_X_FORNARDED_FOR' ， 
'HTTP_X_FORNARDED_HOST ' ， 
'HTTP_X_FORNARDED_SERVER ' ， 


def process_request(self, request): 

Rewrites the proxy headers so that only the most 

recent proxy is used. 

for field in self.FORWARDED_FOR_FIELDS: 

if field in request.META: 
if ',' in request.META[field]: 

parts = request.META[field].split(',') 
request.META[field] = parts[-1].strip() 


这 个 中 间 件 应 该 放 在 使 用 get_host() 所 得 值 的 其 他 中 间 件 前 面 ， 例 如 CommonMiddleware 或 CsrfviewMiddle- 


ware。 


HttpRequest.get_fuLL_path() 


返回 path， 以 及 后 面 的 查询 字符 串 (如 果 有 ) 。 





例如 : /music/bands/the_beatles/?print=true。 


HttpRequest.build absolute_uri(location) 





返回 tocation 对 应 的 绝对 URI。 如 果 未 指定 Location， 使 用 request.get_fuLL_path() 。 


如 果 Location 已 经 是 绝对 URI， 不 再 修改 ， 和 否则 使 用 请 求 中 的 服务 器 参数 构建 绝对 URI。 





例如 : http://exampLe.com/music/bands/the_beatLes/?print=true。 


HttpRequest.get_signed_cookie() 

















返回 指定 签名 cookie 的 值 ， 如 果 签 名 失效 ， 抛 出 django.core.signing.Badsignature 异常 。 如 果 提 供 了 de- 
fault 参数 ， 不 再 抛 出 异常 ， 而 是 返回 指定 的 默认 值 。 


可 选 的 salt 参数 用 于 提供 额外 的 防护 措施 ， 以 免 暴力 攻击 密 钥 。 如 果 提 供 max_age 参数 ， 使 用 它 检查 cookie 
值 的 签名 时 间 戳 ， 确 保 cookie 没有 超过 max_age 指定 的 秒 数 。 


例如 : 

















>>> request.get_signed_cookie( name ') 

"Tony 

>>> request.get_signed cookiel('name', salt='name-salt') 
'Tony' # 假设 cookie 是 使 用 这 个 盐 值 设 定 的 

>>> request.get_signed_ cookie('non-existing-cookie') 
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KeyError: 'non-existing-cookie' 

>>> request.get_signed_cookie('non-existing-cookie', False) 
False 

>>> request.get_signed cookie('cookie-that-was-tampered-with') 


BadSignature: ... 
>>> request.get_signed_cookiel('name', max_age=60) 


SignatureExpired: Signature age 1677.3839159 > 60 seconds 


>>> request.get_signed_cookie('name', False, max_age=60) 
False 


HttpRequest.is_secure() 
为 安全 请 求 时 ， 即 通过 HTTPS 请 求 时 ， 返 回 True。 


HttpRequest.is _ajax() 





检查 HTTP_X_REQUESTED_NITH 首部 中 有 没有 字符 串 "XMLHttpRequest"， 判 断 请 求 是 不 是 通过 XMLHttpRequest 发 
起 的 ， 如 果 是 ， 返 回 True。 多 数 现代 的 JavaScript 库 都 会 发 送 这 个 首部 。 自 己 (在 浏览 器 端 ) 编写 XML- 
HttpRequest 调用 时 ， 若 想 让 is_ajax() 起 作用 ， 要 手动 设 定 这 个 首部 。 


如 果 啊 应 根据 请 求 是 不 是 Ajax 而 有 区 别 ， 而 且 使 用 了 某 种 形式 的 缓存 ， 如 Django 的 缓存 中 间 件 ， 应 该 使 用 
vary_on_headers('HTTP_X_REQUESTED_WITH' ) 装饰 视图 ， 这 样 响应 才能 正确 缓存 。 



























































HttpRequest.read(size=None) 


HttpRequest.readline() 


HttpRequest.readlines() 


HttpRequest.xreadlines() 


HttpRequest.iter() 











t 则 


这 几 个 方法 实现 了 类 似 文件 的 接口 ， 用 于 从 HttpRequest 实例 中 读 取 数据 。 因 此 ， 它 们 能 以 流 的 形式 处 理 入 
站 请 求 。 常 见 的 使 用 场景 是 使 用 迭代 的 解析 器 处 理 大 型 XML， 这 样 无 需 在 内 存 中 构建 整个 XML 树 。 












































因为 接口 是 标准 的 ， 所 以 可 以 直接 把 HttpRequest 实例 传 给 XML 解析 器 ， 如 ElementTree: 











import xml.etree.ElementTree as ET 
for element in ET.iterparse(request): 
process(element) 


F.2 QueryDict 对 象 

















HttpRequest 对 象 的 GET 和 POST 属性 是 django.http.QueryDict 的 实例 ， 这 是 一 个 自 定 义 的 类 似 字典 的 类 ， 能 
处 理 一 个 键 有 多 个 值 的 情况 。 之 所 以 要 有 这 么 一 个 类 ， 是 因为 某 些 HTML 表单 元 素 ， 尤 其 是 <seLect multi- 
ple>， 同 一 个 键 需要 多 个 值 。 






































在 常规 的 请 求 -响应 循环 中 ，request.P0ST 和 request.GET 这 两 个 QueryDict 对 象 是 不 可 变 的 。 若 想 获得 可 变 
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的 版 本 ， 使 用 .copy()。 


F.2.1 方法 









































QueryDict 实现 了 字典 的 所 有 标准 方法 ， 因 为 它 是 字典 的 子 类 。 但 是 ， 下 述 方法 的 行为 有 所 不 同 。 




















QueryDict. init_ _() 
根据 query_string 实例 化 QueryDict 对 象 。 


>>> QueryDict('a=1&a=2&c=3') 
<QueryDict: {'a': ['1', '2'], 'c': ['3']}> 














如 果 未 传人 query_string， 得 到 的 QueryDict 实例 是 空 的 (没有 键 也 没有 值 ) 。 











多 数 QueryDict 对 象 ， 尤 其 是 request.P0ST 和 request.6GET， 是 不 可 变 的 。 如 果 自 己 实例 化 ， 可 以 把 muta- 


ble=True 传 给 _init_(), 创建 一 个 可 变 的 对 象 。 








用 于 设 定 键 和 值 的 字符 串 会 从 encoding 转换 成 Unicode 编码 。 如 果 未 设 定 编码 ， 默 认为 DEFAULT_CHARSET。 


QueryDict. getitem (key) 


XX\ 


























返回 指定 键 对 应 的 值 。 如 果 有 多 个 值 ，__getitem_() 返回 最 后 一 个 值 。 如 果 键 不 存在 ， 抛 出 djan- 








go.utils.datastructures.MultiValueDictKeyError, 


QueryDict. setitem (key, value) 


把 指定 键 对 应 的 值 设 为 [value] (一 个 Python 列表 
其 他 字典 函数 一 样 ， 只 能 在 可 变 的 QueryDict 对 象 

















QueryDict. contains__(key) 





， 只 有 一 个 元 素 value) 。 注 意 ， 这 个 方法 与 有 副作用 的 
(例如 通过 copy() 创建 的 ) 上 调用 。 


如 果 有 指定 的 键 ， 返 回 True。 有 了 这 个 方法 ， 就 可 以 这 样 判断 :if "foo" in request.GET。 














QueryDict.get(key, default) 
































QueryDict.setdefault(key, default) 

















与 _getitem_() 的 逻辑 一 样 ， 但 是 键 不 存在 时 ， 返 回 指定 的 默认 值 。 


与 标准 的 字典 方法 setdefault() 类 似 ， 不 过 内 部 使 用 的 是 _setitem_() 方法 。 





QueryDict.update(other_dict) 

















参数 为 QueryDict 对 象 或 标准 的 字典 。 与 标准 的 字 

















中 方法 update() 类 似 ， 不 过 是 追加 到 现 有 的 元 素 中 ， 而 不 





是 把 元 素 蔡 换 掉 。 例 如 : 


>>> q = QueryDict('a=1', mutable=True) 
>>> q.update({'a': '2'}) 
>>> q.getlist('a') 


| 只 27] 
>>> q['a'] # 返回 最 后 一 个 元 素 
枚 2 
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QueryDict .items() 




















与 标准 的 字典 方法 items() 类 似 ， 不 过 与 _getitem_() 一 样 ， 值 来 自 最 后 一 个 元 素 。 例 如 : 





>>> q = QueryDict('a=1&a=2&a=3') 
>>> q.items() 


[C'a', '3')] 


QueryDict.iteritems() 


























与 标准 的 字典 方法 iteritems() 类 似 ， 同 样 与 QueryDict. getitem () 一 样 ， 值 来 自 最 后 一 个 元 素 。 





QueryDict.iterlists() 

















类 似 于 QueryDict.iteritems()， 不 过 包含 字典 中 每 个 成 员 的 所 有 值 (构成 一 个 列表 ) 。 


QueryDict.values() 

















与 标准 的 字典 方法 values() 类 似 ， 不 过 与 QueryDict. getitem_() 一样 ， 值 来 自 最 后 一 个 元 素 。 例 如 : 





>>> q = QueryDict('a=1&a=2&a=3') 
>>> q.values() 


[*3"] 


QueryDict.itervalues() 


与 QueryDict.values() 类 似 ， 不 过 多 了 一 个 迭代 器 。 


此 外 ，QueryDict 还 定义 了 下 述 方法 。 


QueryDict.copy() 


使 用 Python 标准 库 中 的 copy.deepcopy() 创建 QueryDict 对 象 的 副本 。 即 便 源 对 象 是 不 可 变 的 ， 得 到 的 副本 





也 是 可 变 的 。 


QueryDict.getlist(key, default) 


XX\ 





认 值 不 是 列表 ， 和 否则 始终 返回 列表 。 


QueryDict.setlist(key, list) 














返回 指定 键 对 应 的 值 ( 一 个 Python 列表 ) 。 如 果 键 不 存在 ， 而 且 没 有 提供 默认 值 ， 返 回 一 个 空 列 表 。 除 非 默 























把 指定 的 键 对 应 的 值 设 为 指定 的 列表 (不 同 于 _setitem_()) 。 


QueryDict.appendlist(key, item) 





把 元 素 追 加 到 键 对 应 的 内 部 列表 中 。 


QueryDict.setListdefauLt(key，defautLt_List) 


类 似 于 setdefauLt， 不 过 参数 是 一 个 列 


不 


I 














， 而 不 是 单 











个 值 。 





附录 F 请 求 和 响应 对 象 - 


399 


QueryDict. lists() 
类 似 于 items()， 不 过 包含 每 个 字典 成 员 的 所 有 值 (列表 ) 。 例 如 : 


>>> q = QueryDict('a=1&a=2&a=3') 
25 glists() 
[Lea [1 2 3 


QueryDict.pop(key) 








水 








返回 指定 键 对 应 的 值 〈 列 表 





— 


， 并 把 它们 从 字 — 典 中 删除 。 如 果 键 不 存在 ， 抛 出 KkeyError。 例 如 : 








>>> q = QueryDict('a=1&a=2&a=3', mutable=True) 
>>> q.pop('a') 
[人 2 | 


QueryDict.popitem() 
































随意 删除 一 个 字典 成 员 (因为 字典 是 无 序 的 ) ， 返 回 一 个 两 元 素 元 组 ， 包 含 键 和 对 应 的 值 构成 的 列表 。 在 空 
字典 上 调用 ， 抛 出 KeyError。 例 如 : 





























>>> q = QueryDict('a=1&a=2&a=3', mutable=True) 
>>> q.popitem() 
(5 | 了 2 '3']) 


QueryDict.dict() 








XX\ 






































返回 QueryDict 对 象 的 字典 表示 形式 。QueryDict 对 象 中 的 每 个 (key，List) 对 在 返回 的 字典 中 是 (key， 
item)， 其 中 item 是 List 中 的 最 后 一 个 元 素 (逻辑 同 QueryDict._getitem_()) 。 例如: 





>>> q = QueryDict('a=1&a=3&a=5') 
>>> q.dict() 
{'a': "5 


QueryDict .urlencode([safe]) 





水 


返回 查询 字符 串 形 式 的 字符 串 。 侈 如 





>>> q = QueryDict('a=2&b=3&b=5') 
>>> q.urlencode() 
'a=2&b=3&b=5" 


可 以 指定 无 需 编码 的 字符 。 例 如 : 


>>> q = QueryDict(mutable=True) 
>>> q['next'] = '/a&b/' 

>>> q.urlencode(safe='/') 
'next=/a%26b/" 


F.3 HttpResponse 对 象 























HttpRequest 对 象 由 Django 自动 创建 ， 而 HttpResponse 对 象 要 由 你 自己 创建 。 你 编写 的 每 个 视图 都 要 实例 
化 、 填 充 并 返回 一 个 HttpResponse 对 象 。 
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HttpResponse 类 在 django.http 模块 中 。 


F.3.1 用 法 
传 入 字符 串 





常规 的 用 法 是 把 页 面 内 容 (字符 串 ) 传 给 HttpResponse 构造 方法 : 


>>> from django.http import HttpResponse 
>>> response = HttpResponse("Here's the text of the Web page.'") 
>>> response = HttpResponse("Text only, please.", content_type="text/plain") 








但 是 ， 如 果 想 不 断 添加 内 容 ， 可 以 把 response 视 作 类 似 文件 的 对 象 : 





>>> response = HttpResponse() 
>>> response.write("<p>Here's the text of the Web page.</p>") 
>>> response.write("<p>Here's another paragraph.</p>") 


传 入 迭代 器 











最 后 ， 还 可 以 把 一 个 迭代 器 传 给 HttpResponse 构造 方法 。HttpResponse 将 立即 使 用 和 迭代 器 ， 以 字符 串 形 式 存 
储 内 容 ， 然 后 把 送 代 器 丢掉 。 




















如 果 想 从 欠 代 器 中 以 流 的 形式 把 响应 发 给 客户 端 ， 必 须 使 用 StreamingHttpResponse 类 。 





设 定 首部 字段 


























若 想 为 响应 设 定 首部 字段 ， 或 者 删除 首部 字段 ， 把 它 


区 
车 
愉 





>>> response = HttpResponse() 
>>> response['Age'] = 120 
>>> del response[ 'Age'] 








注意 ， 与 字典 不 同 ， 如 果 要 删除 的 首部 字段 不 存在 ，det 不 抛 出 KeyError。 


设 定 Cache-Control 和 Vary 首部 字段 推荐 使 用 django.utils.cache 中 的 patch_cache_controL() 和 
patch_vary_headers() 方法 ， 因 为 这 两 个 字段 可 以 有 多 个 以 逗号 分 开 的 值 。 这 两 个 方法 能 确保 其 他 值 (例如 
中 间 件 添加 的 ) 不 被 删除 。 



































HTTP 首部 字段 不 能 换行 。 如 果 包 含 换 行 符 (CR 或 LF) ， 抛 出 BadHeaderError。 


让 浏览 器 把 响应 视 作 文件 附件 











若 想 让 浏览 器 把 啊 应 视 作文 件 附件 ， 提 供 content_type 参数 ， 并 设 定 Content-Disposition 首部 。 例 如 ， 下 
述 代码 返回 一 个 Microsoft Excel 电子 表格 : 








>>> response = HttpResponse(my_data, content type='application/vnd.ms-excel') 


>>> response[ 'Content-Disposition'] = 'attachment; filename="foo.xls 




















Content-Disposition 首部 的 值 在 Django 中 没什么 特殊 之 人 处， 但 是 容易 忘记 句法 ， 因 此 我 们 举 了 个 例子 。 
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F.3.2 属性 


HttpResponse .content 








一 个 字 节 字符 串 ， 表 示 响 应 的 内 容 ， 如 果 必 要 ， 编 码 为 Unicode 对 象 。 











HttpResponse .charset 

















一 个 字符 串 ， 表 示 响 应 的 编码 字符 集 。 如 果实 例 化 HttpResponse 对 象 时 没有 指定 ， 从 content_type 中 提取 ， 
如 果 提 取 失 败 ， 使 用 DEFAULT_CHARSET 设置 。 




















HttpResponse.status_code 
响应 的 HTTP 状态 码 。 


HttpResponse.reason_phrase 





响应 的 状态 描述 短语 。 




















HttpResponse.streaming 


始终 为 False。 




















这 个 属性 存在 的 目的 是 让 中 间 件 把 流 式 响 应 与 常规 响应 区 分 开 。 








HttpResponse.closed 


响应 关闭 后 为 True。 














F.3.3 方法 


HttpResponse._ _init() _ 


HttpResponse.__init_ (content='', content_type=None, status=200, reason=None, charset=None) 


使 用 指定 的 内 容 和 内 容 类 型 实例 化 一 个 HttpResponse 对 象 。content 为 一 个 迭代 融 或 一 个 字符 串 。 为 从 代 器 
时 ， 迁 代 器 应 该 返回 字符 串 ， 这 些 字符 串 连 接 在 一 起 构成 响应 的 内 容 。 如 果 不 是 迁 代 器 或 字符 串 ， 访 问 时 将 
被 转换 成 字符 串 。 后 四 个 参数 为 : 





























。 content_type: MIME 类 型 ， 可 从 字符 集 编码 中 推 知 ， 用 于 设 定 HTTP Content-Type 首部 。 如 未 指 
定 ， 由 DEFAULT_CONTENT_TYPE 和 DEFAULT_CHARSET 设置 构成 ， 默 认为 text/htmL; charset=utf-8。 





。 status: 响应 的 HTTP 状态 码 。 
。 reason: 响应 的 状态 描述 短语 。 如 未 提供 ， 使 用 默认 的 短语 。 


。 charset: 编码 响应 所 用 的 字符 集 。 如 未 指定 ， 从 content_type 中 提取 ; 如 果 提 取 失 败 ， 使 用 DE- 
FAULT_CHARSET 设置 。 

































































HttpResponse.__setitem (header, value) 


把 指定 的 首部 设 为 指定 的 值 。header 和 value 都 应 该 为 字符 串 。 
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HttpResponse.__delitem (header) 














删除 指定 的 首部 。 如 果 要 删除 的 首部 不 存在 ， 静 默 。 不 区 分 大 小 写 。 





HttpResponse. getitem (header) 


返回 指定 首部 的 值 。 不 区 分 大 小 写 。 














HttpResponse.has_header (header) 











检查 指定 的 首部 (不 区 分 大 小 写 ) 是 否 存 在 ， 存 在 时 返回 True， 否 则 返回 False。 





HttpResponse.setdefault(header, value) 








设 定 一 个 首部 ， 前 提 是 那个 首部 尚未 设 定 。 


HttpResponse .set_cookie() 


HttpResponse.set_ cookie(key, value='', max_age=None, expires=None, path='/', domain=None, se- 
cure=None, httponly=False) 





设 定 一 个 cookie。 参 数 与 Python 标准 库 中 的 Morsel cookie 对 象 一 样 。 














。 max_age 是 表示 秒 数 的 数字 ， 或 者 为 None (默认 值 ) ， 表 示 cookie 存在 的 时 间 与 客户 端 浏览 器 会 话 一 

样 长 。 如 未 指定 expires， 据 此 计算 。 

。 expires 是 一 个 字符 串 ， 格 式 为 "Wdy，DD-Mon-YY HH:MM:SS GMT"， 或 者 一 个 UTC 时 区 的 date- 
time.datetime 对 象 。 如 果 expires 的 值 是 datetime 对 象 ， 将 据 此 计算 max_age。 

。 domain 用 于 设 定 跨 域 cookie。 例 如 ， 设 定 domain=" .Lawrence.com'" 时 ，www.lawrence.com、 


blogs.lawrence.com 和 calendars.lawrence.com 等 域名 能 访问 cookie。 和 否则 ， 只 有 设 定 cookie 的 域名 才能 
读 取 cookie。 























。 如 果 不 想 让 客户 端 JavaScript 访问 cookie， 设 定 httponly=True。HTTPOnly 是 HITP 响应 首部 Set- 
cookie 中 的 一 个 旗 标 ， 但 不 在 cookie 标准 RFC 2109 中 ， 也 不 是 所 有 浏览 器 都 遵守 。 然 而 ， 如 果 浏 览 
器 遵守 HTTPOntLy 规则 ， 能 降低 客户 端 脚本 访问 受 保护 的 cookie 数据 引发 的 风险 。 



































HttpResponse.set_signed_cookie() 























与 set_cookie() 类 似 ， 不 过 在 设 定 之 前 会 加 密 签名 cookie。 与 HttpRequest.get_signed_cookie() 配对 使 用 。 
可 以 使 用 可 选 的 salt 参数 增加 键 的 强度 ， 但 是 要 记得 把 satt 值 传 给 HttpRequest .get_signed_cookie()。 





HttpResponse.delete cookie() 
删除 指定 键 对 应 的 cookie。 如 果 要 删除 的 键 不 存在 ， 吏 默 。 
鉴于 cookie 的 工作 方式 ，path 和 domain 的 值 应 该 与 传 给 set_cookie() 的 一 样 ， 否 则 无 法 删除 cookie。 
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HttpResponse .write(Ccontent) 
HttpResponse.flush() 


HttpResponse. tell() 


这 三 个 方法 为 HttpResponse 对 象 实现 类 似 文件 的 接口 。 作 用 与 Python 自 带 的 相应 方法 一 样 。 





HttpResponse .getvaLue() 





回 HttpResponse.content 的 值 。 这 个 方法 把 HttpResponse 实例 当做 流 式 对 象 。 


Gd 


HttpResponse.writable() 





始终 为 True。 这 个 方法 把 HttpResponse 实例 当做 流 式 对 象 。 





HttpResponse.writelines(lines) 











把 几 行 内 容 写 人 响应 。 不 添加 换行 符 。 这 个 方法 把 HttpResponse 实例 当做 流 式 对 象 。 





F.3.4 HttpResponse 的 子 类 





























Django 提供 了 几 个 HttpResponse 的 子 类 ， 用 于 处 理 不 同类 型 的 HTTP 响应 。 与 HttpResponse 一 样 ， 这 些 子 
类 也 在 django.http 模块 中 。 











HttpResponseRedirect 








构造 方法 的 第 一 个 参数 是 必须 的 ， 用 于 指定 重 定向 的 目标 路 径 。 可 以 是 完全 限定 的 URL (如 http://www.ya- 
hoo.com/search/) 或 没有 域名 的 绝对 路 径 (如 /search/) 。 构 造 方法 的 其 他 可 选 参数 同 HttpResponse。 注 
意 ，HTTP 状态 码 是 302。 























HttpResponsePermanentRedirect 


库 
等 
IE 
< 
JU 








与 HttpResponseRedirect 类 似 ， 不 过 是 做 永久 重 定 向 (HTTP 状态 码 为 301) ， 而 不 
302) 。 


定向 (状态 码 为 


HttpResponseNotModified 














构造 方法 不 接受 任何 参数 ， 而 且 不 能 为 响应 添加 内 容 。 表 示 自 用 户 上 次 访问 以 来 页 面 没 有 改动 (状态 码 为 
304) 。 






































HttpResponseBadRequest 
与 HttpResponse 类 似 ， 不 过 状态 码 是 400。 
HttpResponseNotFound 


与 HttpResponse 类 似 ， 不 过 状态 码 是 404。 





404 - 附录 F 请 求 和 响应 对 象 


HttpResponseForbidden 
与 HttpResponse 类 似 ， 不 过 状态 码 是 403。 


HttpResponseNotALLowed 








与 HttpResponse 类 似 ， 不 过 状态 码 是 405。 构 造 方法 的 第 一 个 参数 是 必须 的 ， 用 于 指定 允许 的 方法 列表 (如 


['GET', 'POST']) 。 
HttpResponseGone 
与 HttpResponse 类 似 ， 不 过 状态 码 是 410。 


HttpResponseServerError 


与 HttpResponse 类 似 ， 不 过 状态 码 是 500。 








如 果 自 定义 的 HttpResponse 子 类 实现 了 render 方法 ，Django 认为 它 是 在 模仿 SimpleTemplateResponse， 因 此 























render 方法 必须 返回 一 个 有 效 的 响应 对 象 。 





F.4 JsonResponse 对 象 





JsonResponse(data, encoder=DjangoJSONEncoder ，safe=True,，**kwargs) 是 HttpResponse 的 一 个 子 类 , 目的 


是 辅助 创建 JSON 编码 的 响应 。 它 从 超 类 继承 了 多 数 行为 ， 不 过 存在 一 些 差 异 : 




















。 Content-Type 首部 默认 设 为 application/json。 


。 第 一 个 参数 data 应 该 是 一 个 dict 实例 。 如 果 把 safe 参数 设 为 False (参见 下 文 ) ， 则 可 以 是 任何 可 


序列 化 成 JSON 的 对 象 。 








。 encoder 的 默认 值 为 django.core.serializers.json.DjangoJSONEncoder ， 用 于 序列 化 数据 。 





。 布尔 值 参数 safe 默认 为 True。 设 为 False 时 ， 可 以 传人 他 





F 何 可 序列 化 的 对 象 (否则 只 能 传人 dict 实 





例 ) 。 设 为 True 时 ， 如 果 传 给 第 一 个 参数 的 值 不 是 dict 对 象 ， 抛 出 TypeError。 


F.4.1 用 法 
常见 的 用 法 如 下 : 


>>> from django.http import JsonResponse 
>>> response = JsonResponse({'foo': 'bar'}) 
>>> response.content 

foo "bar yy 


序列 化 字典 之 外 的 对 象 


若 想 序列 化 字典 之 外 的 对 象 ， 要 把 safe 参数 设 为 False: 


response = JsonResponse([1, 2, 3], safe=False) 





如 若 不 然 ， 抛 出 TypeError。 
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更 换 默 认 的 JSON 编码 器 















































如 果 想 使 用 其 他 JSON 编码 器 类 ， 把 encoder 参数 传 给 构造 方法 : 








response = JsonResponse(data, encoder=MyJSONEncoder) 


F.5 streamingHttpResponse 对 象 














StreamingHttpResponse 类 的 作用 是 以 流 的 方式 把 Django 的 响应 发 给 浏览 器 。 如 果 生 成 响应 耗 时 太 长 或 耗费 
内 存 太 多 ， 可 以 这 么 做 。 例 如 ， 可 用 于 生成 大 型 CSV 文件 。 




















F.5.1 注意 性 能 




















Django 针对 的 是 短期 请 求 。 在 流 式 啊 应 持续 的 时 间 段 内 ， 它 将 占用 一 个 进程 。 这 可 能 导致 


一 般 来 说 ， 应 该 把 耗资 源 的 任务 放 到 请 求 -响应 循环 之 外 ， 而 不 是 诉 诸 流 式 响应 。 


一 





生 能 下 降 。 




















StreamingHttpResponse 不 是 HttpResponse 的 子 类 ， 因 为 二 者 API 有 点 儿 不 同 。 但 是 ， 除 了 下 述 区 别 之 外 ， 它 
们 的 行为 基本 上 是 一 致 的 。 











。 参数 为 产 出 字符 串 的 迭代 器 。 产 出 的 字符 串 即 响应 的 内 容 。 

。 除非 迭代 响应 对 象 自身 ， 否 则 无 法 访问 响应 内 容 。 只 能 等 到 响应 返回 给 客户 端 之 后 才能 人 迭 代 。 
。 没有 content 属性 ， 而 有 streaming_content 属性 。 

。 不 能 像 类 似 文 件 的 对 象 那 样 调用 teLL() 或 write() 方法 ， 否 则 Django 会 抛 出 异常 。 



























































只 有 十 分 确定 把 数据 发 给 客户 端 之 前 无 法 过 历 内 容 时 才 应 该 使 用 StreamingHttpResponse。 因 为 内 容 无 法 访 
问 ， 所 以 很 多 中 间 件 将 失效 。 例 如 ， 无 法 为 流 式 响应 生成 ETag 和 Content-Length 首部 。 














F.5.2 属性 


StreamingHttpResponse 对 象 有 下 述 属性 : 





。 *,streaming_content: 产 出 字符 串 的 迭代 器 ， 表 示 响 应 的 内 容 。 
。 *.status_code: 响应 的 HTTP 状态 码 。 
。 *.reason_phrase: 响应 的 HITP 状态 描述 短语 。 


。 *.streaming: 始终 为 True。 


F.6 FileResponse 对 象 


FileResponse 是 StreamingHttpResponse 的 子 类 ， 为 二 进 制 文件 做 了 优化 。 它 使 用 wsgi 服务 器 的 ws- 
gi.file_wrapper (如 果 提 供 了 ) ,或 者 以 流 的 形式 发 送 文件 片段 。 











FileResponse 期 望 文件 以 二 进 制 模式 打开 ， 如 下 所 示 : 


>>> from django.http import FileResponse 
>>> response = FileResponse(open('myfile.png', 'rb')) 
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F.7 错误 视图 














ly 








默认 视图 的 方法 参见 F.7.5 市 。 








[eg 




















为 了 处理 HITP 错误 ，Django 自 带 了 几 个 视图 。 使 用 自 定义 的 视 医 





























F.7.1 404 (页 面 未 找到 ) 视图 


defaults.page_not_found(request, template_name='404.html') 























如 果 视 图 抛 出 Http404，Django 加 载 一 个 专门 用 于 处 理 404 错误 的 视图 。 默 认 使 用 的 视图 是 djan- 
go.views.defaults.page_not_found()， 它 生成 一 个 简单 的 “Not Found” 消 息 ， 或 者 泻 染 404.html 模板 〈 如 细 
根 模板 目录 中 有 ) 。 


默认 的 404 视图 向 模板 传递 一 个 变量 ，request_path， 即 致 错 的 URL。 















































a 




















关于 404 视图 要 注意 三 























。 Django 找 遍 URL 配置 ， 如 果 没 有 找到 一 个 匹配 的 正则 表达 式 ， 也 演 染 404 视图 。 















































。 RequestContext 对 象 会 传 给 404 视图 ， 因 此 在 视图 中 可 以 访问 模板 上 下 文 处 理 器 提供 的 变量 (如 ME- 
DIA_URL) 。 

。 DEBUG 设 为 True 时 (在 设置 模块 中 ) ，404 视图 永远 不 会 使 用 ， 此 时 显示 的 是 URL 配置 和 一 些 调试 信 
自 





/DVD 


F.7.2 500 (服务 器 错误 ) 视图 


defaults.server_error(request, template_name='500.html') 























类 似 地 ， 视 图 代码 出 现 运 行 时 错误 时 ， Djange 也 会 表现 出 特殊 的 行为 。 如 果 视 图 抛 出 异常 ，Django 默认 调用 
django.views.defaults.server_error 视图 。 这 个 视图 要 么 生成 一 个 简单 的 “Server Error 消息， 要 么 加 载 并 泻 
染 500.htmt 模板 (如 果 根 模板 目录 中 有 ) 。 


默认 的 500 视图 不 给 569.html 模板 传递 任何 变量 ， 而 是 使 用 空 的 Context 演 染 ， 以 免 再 出 现 其 他 错误 。 







































































DEBUG 设 为 True 时 (在 设置 模块 中 ) ，500 视图 永远 不 会 使 用 ， 此 时 显示 的 是 调用 跟踪 和 一 些 调试 信息 。 





F.7.3 403 (HTTP 禁止 ) 视图 


defaults.permission_denied(request, template_name='403.html') 








与 404 和 500 错误 一 样 ，Django 也 提供 了 处 理 403 Forbidden 错误 的 视图 。 如 果 视 图 抛 出 403 异常 ，Django 
默认 调用 django.views.defaults.permission_denied 视图 。 




















这 个 视图 加 载 并 泻 染 根 模板 目录 中 的 493.htmt 模板 ， 如 果 这 个 模板 不 存在 ， 根 据 RFC 2616 (HITP 1.1 规 
范 ) ， 泻 染 “403 Forbidden” 文 本 。 











django.views.defaults.permission_denied 由 PermissionDenied 异常 触发 。 在 视图 中 如 果 想 拒绝 访问 ， 可 以 
这 人 么 做 : 


from django.core.exceptions import PermissionDenied 


def edit(request, pk): 
if not request.user.is_staff: 
raise PermissionDenied 
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F.7.4 400 ( 坏 请 求 ) 视图 


defaults.bad_request(request, template_name='400.html') 








如 果 Django 抛 出 了 SuspiciousOperation， 可 能 会 由 Django 的 某 个 组 件 处 理 (例如 重 设 会 话 数据 ) 。 如 果 没 
做 特别 处 理 ，Django 将 把 当前 请 求 视 作 “ 坏 请 求 "， 而 不 是 服务 器 错误 。 
































django.views.defaults.bad_request 与 server_error 视图 非常 像 ， 但 返回 的 状态 码 是 400， 表 示 错 误 是 由 客 
户 端 操 作 导 致 的 。 

















bad_request 视图 也 只 在 DEBUG 为 False 时 使 用 。 





F.7.5 自 定义 错误 视图 























Django 自 带 的 默认 错误 视图 对 多 数 Web 应 用 程序 来 说 已 经 够 用 了 ， 但 是 如 果 需 要 定制 行为 ， 也 能 轻易 履 
盖 ， 只 需 按 下 文 所 述 在 URL 配置 中 指定 处 理 程序 (在 别处 设置 不 起 作用 ) 。 


ee 















































er 





page_not_found() 视图 由 handler404 覆盖 : 


handler404 = 'mysite.views.my_custom page_not_found_view' 








server_error() 视图 由 handler500 履 盖 , 














handler500 = 'mysite.views.my_custom error_view' 





permission_denied() 视图 由 handler403 覆盖 : 





handler403 = 'mysite.views.my_custom permission denied view' 
bad_request() 视图 由 handtLer400 覆盖 : 


handler400 = 'mysite.views.my_custom bad_request view' 
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附录 G 使 用 Visual Studio 做 Django 开发 





不 管 你 在 网 上 听 到 怎样 的 抱 急 ， 都 不 得 不 承认 Microsoft Visual Studio (以 下 简称 VS) 一 直 是 功能 极其 强大 的 
集成 开发 环境 (Integrated Development Environment，IDE) 。 作 为 一 名 多 平台 开发 者 ， 我 尝 尽 了 各 种 工具 ， 
最 终 还 是 老 老实 实 使 用 VS。 





























过 去 ， 影 响 VS 普及 的 最 大 障碍 (我 觉得 ) 是 : 
1， 对 Microsoft 生态 系统 《C++、C# 和 VB) 以 外 的 语言 缺少 支持 。 
2， 全 功能 IDE 成 本 高 。Microsoft 腾 肿 的 “免费 "IDE 对 专业 开发 而 言 不 那么 有 用 了 。 


几 年 前 发 布 的 Visual Studio Community Edition ， 以 及 最 近 发 布 的 Python Tools for Visual Studio (以 下 简称 
PTVS) 明显 改变 了 这 一 糟糕 状况 。 如 今 ， 我 的 所 有 开发 工作 ， 不 管用 的 是 Microsoft 相关 的 技术 还 是 Python 
和 Django， 都 在 VS 中 完成 。 



































VS 的 优点 就 不 细 说 了 ， 以 免 你 觉得 我 是 在 给 Microsoft 背书 。 现 在 我 假定 你 至 少 决定 试 一 试 VS 和 PTVS。 














首先 ， 我 要 说 明 如 何在 你 的 Windows 设备 中 安装 VS 和 PTVS， 然 后 ， 简 要 介绍 一 下 可 用 的 Django 和 Python 
工具 。 











G.1 安装 Visual Studio 


安装 前 的 提醒 


VS 毕竟 是 Microsoft 的 产品 ， 因 此 无 法 忽 咯 的 一 个 事实 是 ， 安 装 VS 是 个 艰巨 的 任务 。 为 了 尽 
量 避 免 少 出 问题 ， 请 : 

1， 在 安装 过 程 中 关闭 杀毒 软件 。 

2， 确 保 网 络 连 接 顺畅 。 能 用 有 线 就 别 用 无 线 。 

3， 关 闭 其 他 占用 内 存 和 磁盘 的 程序 ， 如 OneDrive 和 Dropbox。 

4， 关 闭 所 有 无 需 打开 的 程序 。 








做 好 以 上 几 点 之 后 ,访问 VS 的 网 站 ， 下 载 免费 的 Visual Studio Community Edition 2015 (图 G-1) 。! 











1. 现在 的 最 新 版 是 Visual Studio Community Edition 2017， 如 果 想 下 载 2015 版 ， 请 访问 https://msdn.microsoft.com/zh-cn/visual- 
studio-community-vs.aspx。 一 一 译 者 注 
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办 Downloads | Visual Studio x 





wnloads/downloa 





< G 会 重 https://www.visualstudio.com/en- 


pA Visual Stur 


Products patures News Support Marketplace Documentation 





MEE Ne lo Dealloklel 


A rich, integrated development environment for 
creating stunning applications for Windows, Android, 
and iOS, as well as modern web applications and 
doud services 


Learn more > 


Download Community Free 


Compare Visual Studio 2015 editions > 


Visual Studio downloads 








[< | Visual Studio Community [< | ME le lel [< | MRE RYU le [oN ole lS 














图 G-1， 下 载 Visual Studio 


打开 下 载 得 到 的 安装 程序 文件 ， 勾 选 默认 的 安装 选项 (图 G-2) ， 然 后 点 击 “ 安 装 
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dBVSTEISITelie 


Community 2015 


会 更 新 


选择 安装 位 置 
C:\Program Files\Microsoft Visual Studio 14.0 


安装 程序 在 所 有 张 动 圳 中 最 多 需要 8 GB 空间 。 


EL 

包括 C#/VB Web 和 桌面 功能 

自 定 义 (U) 

允许 自 定义 安装 功能 
安装 后 ， 你 可 有 通过 “控制 面板 ”中 的 “程序 和 功能 ”随时 添加 或 删除 其 他 
功能 。 





图 G-2， Visual Studio 的 默认 安装 选项 


现在 ， 你 可 以 去 泡 杯 咖啡 喝 。 可 能 要 喝 上 七 杯 。Microsotft 的 产品 嘛 ， 肯 定 要 等 很 长 时 间 。 网 速 不 同 ， 用 时 也 
不 同 ， 可 能 在 15 分 钟 到 一 个 多 小 时 之 间 。 


少数 时 候 还 可 能 安装 失败 。 (根据 我 的 经 验 ) 这 基本 上 是 因为 忘记 关闭 杀毒 软件 ， 或 者 网 络 暂时 断 连 了 。 痊 
好 VS 的 恢复 功能 足够 强劲 ， 我 发 现 安装 失败 后 它 能 自动 重新 开始 安装 。VS 甚至 能 记 住 之 前 的 位 置 ， 因 此 无 
需 从 头 开始 安装 。 





























G.1.1 安装 PTVS 和 Web Essentials 


安装 好 VS 之 后 ， 添 加 Python Tools for Visual Studio (PTVS) 和 Visual Studio Web Essentials 。 

















在 顶部 菜单 中 选择 “工具 > 扩展 和 更 新 ”( 图 G-3) 。 
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MX 起 页 - Microsoft Visual studio 更 团 加 | 快速 启动 (Ctrl+Q) P= 
文件 。 编辑 (E) ”视图 V) ”诗坛 (D) ”团队 (M) | 工具 MT) | 测试 (S) ”分 析 (N) ”窗口 (W) ”帮助 (H) 有 开 四 
-日 | 闪 - 名 国 出 | -QC-|| | 刘 连 本 到 数据 库 (D). 
号 “连接 到 服务 器 (S).… 
SQL Server(Q) 
[1 代码 片段 管理 露 (T)... Ctrl+K, Ctrl+B 
Visual Studio 由 
NuGet 包 管 理 赦 (IN) 
扩展 和 更 新 (U)… 
开始 创建 GUID(G) 
新 建 项 目 . 错误 查找 (K) 
打开 项 目 ... PreEmptive Protection - Dotfuscator 
在 源 代码 管理 中 打开 . WCF 服务 配置 编 绢 器 (W) 
外 部 工具 (E)… 
导入 和 导出 设置 加.… 
最 近 自 定义 ( 〇 .. 
选项 (O).… 





别 Windows 
SY Microsoft A: 
ww ASP.NET 和 ' 


新 闻 解决 方案 资源 管理 器 上 | 具 2raEE 省 咯 二 | 





图 G-3; 安装 Visual Studio 扩展 











在 打开 的 “扩展 和 更 新 "窗口 中 选择 左边 的 "联机 "， 进 入 VS 在 线 应 用 集 。 在 右上 角 的 搜索 框 中 输入 "Python ， 
第 一 个 搜索 结果 应 该 就 是 PTVS 扩展 (图 G-4) 。? 











2. 如 果 点 击 “ 下 载 ”按钮 后 打开 Visual Studio 网 站 ， 让 你 重新 下 载 Visual Studio， 请 跳 过 这 一 步 。 在 G.2.1 节 新 建 项 目 时 会 提示 
你 安装 所 需 的 扩展 ， 根 据 提示 安装 即 可 。 一 一 译 者 注 
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-二 x 
bP 已 安装 排序 依据 : 关联 ~ python 全 
4 联机 Pytnon RS Vi Sind ee 创建 者 : HPCToolsGuy 

TVS is a free/O | osoft that 
4 Visual studio 库 ee 下 载 : 194633 
s VS into a Python IDE (Express/Pro). Suppor... 
搜索 结果 评级 : 六 太太 太夫 (18 投票 ) 
工具 舍 Scanner.js: JavaScript Scan in Chrome, IE to C# VB AS... 详细 信息 
b 控件 Scannerjs enables HTML JavaScript scanning in web browsers 向 Microsoft 报告 扩展 
模板 (Chrome, Edge, Firefox, IE). Scan documents from TWAIN WIA s... 
b 示例 库 [yy Search In Velocity 
Provides a command to search in Velocity - the offline 
”更 新 (外 documentation and docset viewer for Windows 
四 ImageComments 
Use images in code comments. Either from the web or from the 
local disc. 
RSS ODBC Driver 
The RSS ODBC Driver is a powerful tool that allows you to 
connect with live RSS feeds, directly from any applications that s… 
首 Twitter ODBC Driver 
The Twitter ODBC Driver is a powerful tool that allows you to 
connect with live data from Twitter directly from any application... 
WE Veracode Visual Studio Extension 4 
1 
更 改 扩展 和 更 新 设置 











以 同样 的 方式 安装 VS Web Essentials (图 G-5) 。 注 意 ， 如 果 使 用 其 他 的 VS 构建 版 ， 或 者 之 前 安装 过 一 些 扩 
展 ，Web Essentials 可 能 已 经 安装 了 。 如 果 是 这 样 ,“ 下 载 ” 按 钮 所 在 的 位 置 会 显示 一 个 绿色 对 号 图 标 。 














新 二 
bP 已 安装 排序 依据 : 关联 各 web 和 
Web Search 2 _， 创建 者 : Mads Kristensen 

4 Visual studio 库 es Integrated search options for Visual Studio IDE with 版 本 : 3.0.235 
?工具 下 载 : 577650 
b 控件 YP, Web Application Server 评级 : 太太 太志 让 (139 投票 ) 
b 档 板 # F#, Owin, ASP.NET Identity, SignalR... lt can be used as a back-end 详细 信息 
server for a single-page application (SPA), exposing only OAuth... 向 Microsoft 报告 扩展 
bp 示例 库 ‘= DevExpress Web Dashboard 
DevExpress Web Dashboard Control ships with a comprehensive 
”更 新 (4) feature set designed to elevate its design capabilities and bring... 
则 > Web Accessibility Checker 
Ws The easiest way to perform accessibility checks on any ASP.NET 
web application. Fully customizable and support all the major int… 
@ Web Processes Killer 
Web Processes Killer Extension for Visual Studio. 
This simple extension adds a "Kill Web Processes" command to... 
Web Essentials 2015.3 下 载 (D) 
Adds many useful features to Visual Studio for web 
developers. Requires Visual Studio 2015 
SP RapidSpell Web ASP.NET 要 
2 
更 改 扩展 和 更 新 设置 








G-5， 安装 Web Essentials 扩展 


G.2 创建 Django 项 目 


使 用 VS 做 Django 开发 最 大 的 好 处 之 一 是 ， 除 了 VS 自身 以 外 ， 只 需 安装 Python。 如 果 你 已 经 按 第 1 章 所 述 
安装 了 Python， 就 什么 都 不 用 做 了 ，YVS 会 负责 创建 虚拟 环境 、 安 装 所 需 的 Python 模块 ， 甚 至 还 在 IDE 中 内 
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置 了 Django 的 所 有 管理 命令 。 








为 了 演示 这 些 功能 ， 下 面 我 们 来 创建 第 1 章 中 的 mysite 项 目 ， 不 过 这 一 次 都 在 VS 中 操作 。 





G.2.1 新 建 一 个 Django 项 目 





在 顶部 菜单 中 选择 “文件 > 新 建 > 项 目 "， 然 后 在 左边 的 下 拉 菜 单 中 选择 Python Web 项 目 。 你 应 该 看 到 如 图 
G-6 所 示 的 界面 。 选 择 “Blank Django Web Project”*， 输 入 项 目 名 称 ， 然 后 点 击 “ 确 定 ”。 



































建 项 上 
” 最近 NET Framework 4.5.2 ~ 排序 依据 : 默认 值 ~ 司 搜索 已 安装 模板 (Ctr|+E) 
4 已 安装 2 

[A Azure Cloud Service Python 类 型: Python 

4 模板 = i A project for creating a Django 

b Visual C# 印 Web Project Python project 
b Visual Basic PY 
Visual F# 锚 Bottle Web project Python 
b Visual C++ PY 区 i 
SQL Server 甸 jango Web Proj Python 
py 
beveennt [| Flask Web Project Python 
4 Python 
PY 
Web 名 Flask/Jade Web Project Python 
Windows IoT Core 
: PY 
b TypeScript 怨 Blank Bottle Web project Python 
游戏 
生成 jn 速 器 Blank Django Web Project 
bP 其 他 项 目 类 型 APY v 
bP 联机 tb 可 

名 称 (N): DjangoWebprojectl 
位 置 (D): ci\users\a4012\documents\visual studio 2015\Projects ~ 浏览 (B)… 
解决 方案 名 称 (M): DjangoWebprojectl Y| 为 解决 方案 创建 目录 (D) 

添加 到 源 代码 管理 (U) 








图 G-6， 创建 一 个 空 Django 项 目 

















然后 Visual Studio 会 弹出 一 个 窗口 ， 提 示 项 目 需要 额外 的 包 (图 G-7) 。 这 里 ， 最 简单 的 选择 是 直接 安装 到 
虚拟 环境 中 (选项 1) ， 但 是 这 样 会 安装 最 新 版 Django (写作 本 书 时 是 1.9.7) 。 因 为 本 书 是 针对 1.8 LTS 版 
本 的 ， 所 以 我 们 要 选择 选项 3,，“] will install them myself”( 稍 后 我 自己 安装 ) ， 对 requirements.txt 文件 做 
必要 的 改动 。 
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This project requires external packages 


We can download and installthese packages foryou automatically but we need to know whether 
you want to installthem forjust this project orfor all your projects, 


一 Install into a virtual environment... 
Packages will only be available for this project (recommended) 


一 Install into Python 3.4 
Packages will be shared by all projects 


—> 1 will install them Dose 


G-7， 安 装 额 外 的 包 








项 目 创建 好 之 后 ， 在 VS 界面 右 侧 的 “解决 方案 资源 管理 器 ”中 你 会 看 到 完整 的 Django 项 目 结构 已 经 为 你 创建 
好 了 。 接 下 来 要 添加 一 个 运行 Django 1.8 的 虚拟 环境 。 写 作 本 书 时 ， 最 新 版 是 1.8.13， 因 此 我 们 要 把 re- 
quirements.txt 文件 的 第 一 行 改 成 : 














django==1.8.13 


保存 文件 ， 然 后 在 “解决 方案 资源 管理 器 "中 右键 点 击 “Python Environments”(Python 环境 ) ， 选 择 “Add Virtu- 
al Environment”( 添 加 虚拟 环境 ) (图 G-8) 。 

















日 日 和 从 | 上 -有 避 轩 | 上 -一 
搜索 解决 方案 资源 管理 更 (Ctr|+;) 


网 解决 方案 “mysite”(1 个 项 目 ) 
4 [PY] i 


Add/Remove Python Environments... 
Add Virtual Environment... 
Add Existing Virtual Environment... 


View All Python Environments 


限定 为 此 范围 (9) 














图 G-8， 添 加 虚拟 环 


汪 





在 弹出 的 窗口 把 默认 的 环境 名 称 “env” 改 为 更 有 意义 的 名 称 (如 果 你 跟着 第 1 章 的 示例 做 ， 命 名 为 
env_mysite) 。 点 击 “Create”( 创 建 ) ， 此 时 VS 会 创建 一 个 虚拟 环境 (图 G-9) 。 
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使 用 VS 时 无 需 手 动 激活 虚拟 环境 ， 因 为 所 有 代码 都 自动 在 "解决 方案 资源 管理 咒 " 中 激活 的 虚 
拟 环境 里 运行 。 这 样 便于 使 用 Python 2.7 和 3.4 测试 代码 一 一 只 需 右键 点 击 ， 激 活 需要 的 环 
境 。 





Add Virtual Environment 
Location of the virtual environment 


Specify the name or location of the virtual environment. If one already exists we will 
detect the base interpreter for you， 


Select an interpreter to create the virtual environment from,. 


Packages in your base interpreter will not be available in the virtual environment until 
you install them,. 


Python 3.4 


We found a requirements,.tbxt file. 


This file contains external packages that are required by your project. We can use pip to 
download and install these dependencies automatically. 


Vv Download and install packages 


Actions we will perform: 


* Create a virtual environment 
s Install packages from requirements,bd 





G-9， 创建 虚 拟 环 境 


G.3 在 Visual Studio 中 做 Django 开发 


Microsoft 做 了 很 大 努力 ， 确 保 在 VS 中 开发 Python 应 用 程序 尽量 简单 和 无 痛 。 对 新 手 程序 员 来 说 ， 最 棒 的 功 
能 是 所 有 Python 和 Django 模块 都 有 完整 的 IntelliSense 支持 。 这 一 功能 能 加 快 学 习 过 程 ， 无 需 翻阅 文档 ， 查 
看 模块 的 实现 。 





VS 还 在 其 他 方面 简化 了 Python/Django 编程 : 


1. 集成 Django 管理 命令 
2.， 便于 安装 Python 包 
3. 便于 安装 新 的 Django 应 用 
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G.3.1 对 Django 管理 命令 的 集成 


Django 常用 的 管理 命令 都 在 “项 目 " 菜 单 中 (图 G-10) 。 


DA mysite - Microsoft Visual studio 
文件 Fi) ”编辑 (E) ”视图 (V) | 项 目 (P) | 生成 (B) ”调式 (D) 团队 (M) ”工具 (D) ”测试 (\) Web Es 


-日 | 前- 各 | 条 ”添加 新 项 (W)... Ctrl+Shift+A » 

沸 : 加 ”添加 现 有 项 (G)... Shift+Alt+A | 
requirements.txt 二 X 

1 django=1. 8 添加 ASP.NET 文件 夫 (S) » | 


Open Django Shell 
Django Check (Django >= 1.7) 
Django Make Migrations (Django >= 1.7) 
Django Migrate... (Django >= 1.7) 
Django Create Superuser (Django >= 1.7) 
Collect Static Files 
Run PyLint 
Start server 
Start debug server 
Validate Django App... (Django <= 1.6) 
Django Sync DB... (Django <= 1.6) 

[ 峡 显示 所 有 文件 (D) 

添加 引用 (R)... 

Add Connected Service... 

设 为 启动 项 目 (A) 

管理 NuGet 程序 包 (N).… 

mysite 尾 性 (P).… 





咎 时 答对 


9 


图 G-10: “项 目 ” 菜 单 中 常用 的 Django 命令 





在 这 个 菜单 中 可 以 运行 迁移 、 创 建 超级 用 户 、 打 开 Django shell 和 运行 开发 服务 器 。 





G.3.2 简化 Python 包 的 安装 


在 “解决 方案 资源 管理 器 "中 可 以 直接 把 Python 包 安 装 到 任何 虚拟 环境 中 ， 只 需 在 环境 上 点 击 右键 ， 然 后 选择 
“Install Python Package...” (安装 Python 包 ) (图 G-11) 。 
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©9 人 |e-5sa 久 |p 一 


Search Solution Explorer (Ctrl+;) 有- 


团 Solution ,mysite (1 project) 
4 [PY mysite 
4 加 Python Environments 













前 se Install Py 3 
前 wl Install from requirements.bct 
mm Referenc! 
mm Search Pa Generate requirements,bd 
bp 记 mysite Scope to This 
PY manage New Solution Explorer View 
国 requirem 
从 “Remove Del 
CGOpen Folderin File Explorer 
python Environments 
Open Command Prompt Here... 


Properties Copy Full Path 






Properties 





图 G-11， 安 装 Python 包 


包 可 以 使 用 pip 或 easy_install 安装 。 


G.3.3 简化 新 Django 应 用 的 安装 


最 后 ， 在 项 目 中 添加 新 的 Django 应 用 也 很 简单 ， 只 需 在 项 目 上 点 击 右键 ， 然 后 选择 “添加 > Django app.…. 
”( 图 G-12) 。 输 入 应 用 的 名 称 ， 然 后 点 击 “OK”，VS 就 会 在 项 目 中 添加 一 个 新 应 用 。 
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eof|le-.s 和 | 


搜索 解决 方案 资源 管理 器 (Ctrl+) 


网 解决 方案 “mysite”(1 个 项 目 ) 
4 加 mysite 





生成 (U) 

重新 生成 (6) 

清理 (N) 

发 布 (B)... 

Python 

Web Essentials 
限定 为 此 范围 (S) 

新 建 解决 方案 资源 管理 器 视图 (N) 





管理 NuGet 程序 包 (N).… 
设 为 启动 项 目 (A) 

调试 (G) 

源 代码 管理 (S) 











配 呈 字 


- 
Pe 


Del 引用 (R)... 





新 建 项 (W).. Ctrl+Shift+A 
现 有 项 (G)... Shift+Alt+A 
新 建文 件 夫 (D) 

» Existing Folder... 

Ctrl+X 将 现 有 项 目 作为 Azure WebjJob 


th Connected Service... 








图 G-12， 添 加 Django 应 用 


以 上 只 是 快速 浏览 一 下 Visual Studio 的 功能 ， 以 便 让 你 快速 上 手 。 还 有 一 些 功 能 值得 一 用 : 


。 VS 的 仓库 管理 功能 ， 例 如 与 本 地 Git 仓库 和 GitHub 深度 集成 。 

。 使 用 免费 的 MSDN 开发 者 账号 部 署 到 Azure (写作 本 书 时 只 支持 MySQL 和 SQLite) 。 
。 内 置 混合 模式 调试 器 。 例 如 ， 可 以 在 同一 个 调试 器 中 调试 Django 和 JavaScript。 

。 内 置 对 测试 的 支持 。 


。 前 文 提 过 的 全 面 





IntelliSense 支持 。 
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